Checkr Trust is a modern, RESTful API-driven service designed to enhance trust and safety for your platform. The Checkr Trust API uses resource-oriented URLs, supports HTTPS for authentication and requests, and returns JSON responses.

The Checkr Trust API provides access to a rich set of data, including criminal records, traffic infractions, and registry checks. Once credentialed, you can start testing locally in minutes. For additional resources, please refer to our resource center. This documentation aims to help you quickly utilize Checkr Trust’s services, offering context and technical guidance for working with the API.

Important: Checkr Trust is not a “consumer reporting agency” or otherwise a producer of “consumer reports,” as those terms are defined in the Fair Credit Reporting Act (“FCRA”). Checkr Trust data must not be accessed, obtained, disclosed, or otherwise used to make any decisions related to credit, insurance, employment, or any other purposes described in 15 U.S.C. § 1681b of FCRA

The following sections will guide you through the steps necessary to start running checks with the Checkr Trust API:

• Get credentialed
• Authenticate with Checkr Trust
• Create a New Profile
• Create a New Check
• Parse Check Results
• Create a New Driver Check
• Parse Driver Check Results
• Create a New Identity Verification
• Parse Identity Verification Results

Before you can request data from this API, you must first work with a Checkr Trust Account Executive or Customer Success representative to set up and credential your account.

Best practices for securing your API credentials:

• Do not store your credentials in your codebase or commit them to version control. Instead, securely store the key only in your production environment, such as in environment variables.
• Do not store your API key on the client side. All requests should be made from the server side, and only necessary data should be passed to the client.
• If an API key is compromised, contact Checkr Trust immediately to revoke it. Checkr Trust will expire the current key and your Account Executive or Customer Success Representative will issue you a new one.

Your API key can be used to make any API call on behalf of your account, such as creating profiles and checks. Currently, your API key has unlimited access and must be secured accordingly. Checkr Trust will provide you with your Client Key and Secret Key, which can be exchanged for an access token via OAuth. The generated access tokens expire in 24 hours if not refreshed. Below is a step-by-step guide.

OAuth 2.0 Overview

OAuth 2.0 is an authorization framework that allows applications to obtain access to a HTTP service. User authentication is delegated to the service that hosts the user account, while third-party applications are authorized to access the user account.

Terminology

• Resource Owner: The user authorizing an application to access their account.
• Client: The application requesting access to the user's account.
• Authorization Server: The server authenticating the Resource Owner and issuing access tokens to the Client.
• Resource Server: The server hosting protected resources, capable of responding to requests using access tokens.

OAuth 2.0 Flow

1. Authorization Request
2. Authorization Grant
3. Access Token Request
4. Access Token Response

Obtaining an Access Token

Step 1: Register Your Application

Before you start, register your application with the Authorization Server to obtain your client_id and client_secret.

Step 2: Access Token Request

Make a POST request to the token endpoint with your client_id and client_secret in the body.

Example Request

$ curl --location 'https://api.checkrtrust.com/v1/accounts/token' \
--header 'Content-Type: application/json' \
--data '{
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET"
}'

Step 3: Access Token Response

If the request is successful, the Authorization Server responds with an access token, scopes, expiration time, and token type.

Example Successful Response:

{
"access_token": "eyJhb...(something long)...qJFlg",
"scope": "read:account create:account delete:account",
"expires_in": 86400,
"token_type": "Bearer"
}

If the request fails, the Authorization Server responds with an error message.

Example Error Response:

{
"error": "access_denied",
"error_description": "Unauthorized"
}

Using the Access Token

Include the access token in the Authorization header when making requests to the Resource Server.

Example Request

curl --location 'https://api.checkrtrust.com/v1/checks' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ACCESS_TOKEN' \
--data '{
    "first_name": "John",
    "last_name": "Smith",
    "dob": "19880218"
}'

Error Handling

If any step in the OAuth 2.0 flow encounters an error, the Authorization Server returns an error response. These errors can include invalid requests, invalid clients, and invalid grants.

Profiles represent a set of Personally Identifiable Information (PII) for a person who will be checked. Profiles can be updated with the latest information for a person and be referenced to generate checks.

Checks provide the resulting information relevant to the requested check for a set of PII. The response will include the check type and results.

Create a New Check

Creates a new check resource.

Required Fields The required attributes for a check resource vary depending on its intended use. Each check requires a minimum set of attributes. You can pass through the minimum set of PII or a profile_id to reference the profile’s PII. If both parameters are passed, the PII from the profile will take precedence. If the PII is insufficient for a check, a validation error will return a 401 Bad Request. Fields required to generate an Instant Criminal Check include:

• first_name
• last_name
• dob (date of birth)

Parse Check Results

Synchronous responses for a check and GET requests for a check both contain the same information about the results of the check. A completed check with empty results indicates that there are no items on the person’s record for review. Results that are populated indicate items on the check that may require review. Results may not be used to determine eligibility for credit, insurance, employment, or any other purpose regulated under the FCRA. Additionally, Checkr Trust does not make any policy decisions on behalf of its customers.

Driver checks provide the resulting information relevant to the requested driver license. The response will include the driver check type and results.

Create a New Driver Check

Creates a new Driver Check.

Required Fields The required attributes for a driver check vary depending on its intended use. You can pass through the minimum set of PII or a profile_id to reference the profile’s PII. If both parameters are passed, the PII from the profile will take precedence. If the PII is insufficient for a driver check, a validation error will return a 401 Bad Request. Fields required to generate a Driver Check include:

• first_name
• last_name
• dob
• driver_license_number
• driver_license_state

Parse Driver Check Results

Asynchronous responses for a Driver Check and GET requests for a Driver Check both contain the same information about the results. You must expose a Webhook endpoint on your end to receive Driver Check completion events. Please work with a Checkr Trust Account Executive or Customer Success representative to set up this Webhook endpoint on your account. Additionally, Checkr Trust does not make any policy decisions on behalf of its customers.

Identity Verifications provide the resulting information relevant to the requested verification for a set of PII. The response will include the IDV type and results.

Create a New Identity Verification

Creates a new Identity Verification resource.

Required Fields The required attributes for an Identity Verification resource vary depending on its intended use. You can pass through the minimum set of PII or a profile_id to reference the profile’s PII. If both parameters are passed, the PII from the profile will take precedence. If the PII is insufficient for a verification, a validation error will return a 401 Bad Request. Fields required to generate an Identity Verification include:

• first_name
• last_name
• idv_type
• any of email, phone, dob or address

Parse Identity Verification Results

Synchronous responses for an Identity Verification and GET requests for an Identity Verification both contain the same information about the results. A completed Identity Verification will provide match scores for each attribute provided (first name, last name, email, phone, etc); and an overall match score. Additionally, Checkr Trust does not make any policy decisions on behalf of its customers.

Endpoints and operations having to do with accounts and authorization. Account creation and credentialing will be done with a Checkr Trust team member.

Checks provide the resulting information relevant to the requested check for a set of PII. Checks will include the Check type and results.

Driver Checks provide the resulting information relevant to the requested driver license. The response will include the driver check type and results.

Identity Verifications provide the resulting information relevant to the requested verification for a set of PII. The response will include the IDV type and results.

Profiles represent a set of Personally Identifiable Information (PII) for a person who will be checked. Profiles can be updated with the latest information for a person and be referenced to generate checks.