Background Check Providers

How it works

The first step is for Workable and the Background Check Provider to be authenticated. Then, the user can select one from the available/configured packages from the Provider and push a candidate's information over to create a new background check request. The provider requests from candidate to consent or reject the background check and the provider informs the user about the status. When the candidate gives consent and the background check is completed, the Provider should inform Workable about the results.

There are 2 endpoints that should be provided, with ${BASE_URL} being the root path for both of them:

1. https://${BASE_URL}/packages which allows the GET method and lists the available types of checks (packages).
2. https://${BASE_URL}/checks which allows the POST method and creates a background check request for a candidate

Workable provides an endpoint for receiving the results, see creating a check for more info.

Authentication

1. Workable to Background Check Provider

Every call from Workable towards the Background Check Provider is authenticated using an access token contained in the Authentication HTTP Header. e.g. Authorization: Bearer 78e3be68d98268509ea304a506ed6362d. This token should be provided to the user from the Background Check Provider and configured in the respective Workable account.

2. Background Check Provider to Workable

Regarding the requests originating from the Background Check Provider, an access token will be generated and communicated upon the integration creation. This token should be included in the Authorization Header as well.

The Bearer token is the standard authorization scheme used in OAuth 2

Listing available packages

Workable needs access to the available/configured packages; an authenticated GET is triggered towards the Background Check Provider to fetch them. The endpoint should be formatted as https://${BASE_URL}/packages and the response should be a JSON document with an array of packages. Each package is described through identification and name.

Response

{
  "packages": [
    {
      "id": 1,
      "name": "Criminal Pro"
    },
    {
      "id": 2,
      "name": "Motor Vehicle Standard"
    }
  ]
}

Create a Background Check

Workable provides users with the ability to create a background check request for a candidate on demand. If the action is called, Workable will POST the Background Check Provider on https://${BASE_URL}/checks with a payload that looks as follows:

{
  "package_id": "12345",
  "job_title": "Operations Manager",
  "callback_url": "https://groove-tech.workable.com/checks/8823119",
  "candidate": {
    "first_name": "Lakita",
    "last_name": "Marrero",
    "phone": "(785)991-6256",
    "email": "[email protected]",
  },
  "preferences": {
    "key": "value"
  }
}

• package_id: The identification provided in the previous step
• job_title: The job that the candidate applied to. Can be contained in the request email.
• callback_url: The URL in which the Background Check Provider should publish the results (see below)
• candidate: Candidate info. Can be used in the request email.
• preferences: This field can be used to pass custom values to the Background Check Provider.

The Background Check Provider should respond with a 201 status and an identifier for the created background check.

JSON

{ "background_check_id": "2044922" }

Results collection

1. Publishing the Results to Workable

There are 5 statuses for a background check request. The initial status is pending and then the background check can be consented, completed, declined or expired. The status depends on the actions of the candidate regarding the background check request. Whenever the status changes, the Background Check Provider should publish the new status to Workable using PUT on the callback_url provided in the background check creation step.

When the status is completed, the request should include the background check results.

2. Publishing the Results on an API

Another alternative is for Workable to poll the endpoint https://${BASE_URL}/checks/:id with the check identifier returned in the check creation step. This method however is suboptimal since it requires more than one requests until the results are finally fetched. Moreover, a failsafe mechanism should be created in case the request was declined by the candidate.

In both cases the payload provided by the Background Check Provider should be as follows:

{
  "results_url": "https://acme.com/checks/2044922",
  "status": "completed",
  "check": {
    "overall_status": "consider"
    "result": [
        {
          "name": "motor_vehicle_report",
          "status": "clear"
        },
       {
          "name": "education_verification",
          "status": "consider"
        }
    ]
  },
  "attachments": [
    {
      "description": "Background Check Report",
      "url": "https://acme.com/checks/2044922/report.pdf"
    }
  ]
}

Mandatory fields

• status: This can take any of the values consented,completed, declined or expired
• results_url: A link to the fully-fledged report on the Provider's site (Mandatory only when status is completed)

Optional fields

• check:
  • overall_status: The final result of the report, generally if one of the subreports has status consider then the overall status should be consider too.
  • result: This can be used to provide a deeper analysis on the candidate's results. It's a JSON with one level nested objects and is presented to the user with minimum formatting, so keys should be descriptive and readable. The structure should follow the key: value format. Any values holding dates should conform to ISO 8601.
• attachments: Currently only supporting PDF. A results report of the background check along with a description, if available. The URL should be publicly accessible.

Errors

The endpoints of the Background Check Provider should handle request errors with a status code followed by a readable message. The description message should be short yet verbose enough to facilitate ease of troubleshooting.

A valid response on an Error would be

JSON

{ "status": 401, "message": "Invalid Token" }

3. Retrieving a shared link

This is an optional GET endpoint to be implemented by the Background Check Provider. This endpoint serves background check links, in cases where the system supports sharing public links. The URL should look like https://${BASE_URL}/checks/:id/shared-link and the check-id should be the one returned from the background check creation call.

Response

{
  "url": "https://acme.com/checks/2044922/link",
  "ttl": "120",
  "ttl_units": "minutes"
}

• url: A link to the public shared report on the Provider's site
• ttl: (Optional) The time this link will be available. If this is not set, the link is assumed to be permanent.
• ttl_units: The units used for measuring the TTL. Currently supported values: minutes, days and views.