# Checkr Trust API

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.

## Intended Use Cases

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


Version: 1.0
License: Proprietary

## Servers

Checkr Trust API
```
https://api.checkrtrust.com/v1
```

## Security

### get-bearer-token-using-oauth2

Machine-to-machine (M2M) OAuth 2.0 **client credentials** flow.

1. Exchange your `client_id` and `client_secret` at
   [`POST /accounts/token`](#operation/post-accounts-token)
   (see [Authentication](./index.md#authentication)).
2. Call protected endpoints with `Authorization: Bearer <access_token>`.

Access tokens are JWTs. Lifetime is returned as `expires_in` (typically 24 hours).
Request a new token when the current one expires — there is no refresh-token
grant on this public token endpoint.


Type: oauth2

## Download OpenAPI description

[Checkr Trust API](https://docs.checkrtrust.com/_bundle/v1.yaml)

## Accounts

Account credentialing and OAuth 2.0 **client credentials** token issuance
([`POST /accounts/token`](#operation/post-accounts-token)). See
[Authentication](./index.md#authentication) for the end-to-end flow.
Account creation and environment setup are done with a Checkr Trust team
member.


### Create token

 - [POST /accounts/token](https://docs.checkrtrust.com/v1/accounts/post-accounts-token.md): Exchange your Checkr Trust client_id and client_secret for a Bearer
access token (OAuth 2.0 client credentials).

- grant_type is optional; when sent it must be client_credentials.
  Any other value returns 400.
- scope in the request body is optional and ignored; scopes on the
  token come from your Auth0 client configuration.
- Successful Auth0 responses are returned as 200 with the standard
  token fields (access_token, token_type, expires_in, scope).
- Invalid credentials or Auth0 rejections are passed through (typically
  401) with Auth0's OAuth error body.
- If the authentication provider returns an unexpected or unparsable
  response, a 500 is returned with the standard API error array.

Step-by-step guide: Authentication.

## Instant Criminal Checks

Instant Criminal Checks provide the resulting information relevant to the requested check for a set of PII. Checks include the check type and **results**.

**Results and confidence scoring:** Each criminal **case** inside `results[].cases[]` may include `identity_match_confidence_level` when identity matching applies. That field summarizes how well the case matches the subject you searched (high, medium, low, or special values such as unknown or insufficient_information). See the `case` schema in the checks component for full semantics.


### Get checks

 - [GET /checks](https://docs.checkrtrust.com/v1/instant-criminal-checks/get-checks.md): Get a set of checks

### Create check

 - [POST /checks](https://docs.checkrtrust.com/v1/instant-criminal-checks/post-checks.md): Create a new check.

{% partial file="/_partials/profile-id-pii-mutual-exclusivity.md" /%}

### Get check

 - [GET /checks/{check_id}](https://docs.checkrtrust.com/v1/instant-criminal-checks/get-check-by-id.md): Get a single check with a given id

### Download check report (PDF)

 - [GET /checks/{check_id}/report](https://docs.checkrtrust.com/v1/instant-criminal-checks/get-check-report-pdf.md): Download a PDF report for a single instant criminal check. The file is returned as an attachment
(Content-Disposition: attachment) with a suggested filename of checkr_trust_report{check_id}.pdf.

The PDF reflects the same result shaping as the JSON check resource.

Availability: Returns 422 Unprocessable Content with a JSON body when the check has not finished
and results are not yet available (no completed results).

## Profile Criminal Checks

Profile Criminal Checks provide a people-data-graph-native, profile-centric alternative to
Instant Criminal Checks. Instead of a flat records array, `results` is an array of matched
identities (profiles) -- each with a conservative identity summary and its own nested
criminal records -- so you can review which identity matched before drilling into its records.

{% partial file="/_partials/beta-provisional-notice.md" /%}


### Create profile criminal check

 - [POST /profile_criminal_checks](https://docs.checkrtrust.com/v1/profile-criminal-checks/post-profile-criminal-checks.md): Create a new profile criminal check. Unlike Instant Criminal Checks, results is an array
of matched identities (profiles) with their own nested records, rather than a flat records
array -- so a customer can first review which identity matched before drilling into its
records.

{% partial file="/_partials/beta-provisional-notice.md" /%}

{% partial file="/_partials/profile-id-pii-mutual-exclusivity.md" /%}

### Get profile criminal check

 - [GET /profile_criminal_checks/{check_id}](https://docs.checkrtrust.com/v1/profile-criminal-checks/get-profile-criminal-check-by-id.md): Get a single profile criminal check with a given id.

{% partial file="/_partials/beta-provisional-notice.md" /%}

## Criminal Checks

Criminal Checks provide criminal record check results delivered asynchronously via webhook.

### Get criminal checks

 - [GET /criminal_checks](https://docs.checkrtrust.com/v1/criminal-checks/get-criminal-checks.md): Get a set of criminal checks. Results are only available after webhook delivery.

### Create criminal check

 - [POST /criminal_checks](https://docs.checkrtrust.com/v1/criminal-checks/post-criminal-checks.md): Create a new criminal check. The check runs synchronously but results are only delivered via webhook.

{% partial file="/_partials/profile-id-pii-mutual-exclusivity-reference-id-allowed.md" /%}

Important Notes:
- Results are NOT returned in the HTTP response (returns 202 Accepted)
- Results are delivered asynchronously via webhook
- Webhook destination_url must be configured in product configuration

### Get criminal check

 - [GET /criminal_checks/{criminal_check_id}](https://docs.checkrtrust.com/v1/criminal-checks/get-criminal-check-by-id.md): Get a single criminal check with a given id. Results are only visible after webhook delivery.

## County Checks

County Checks provide county-level criminal background check results for a specific jurisdiction. Results are retrieved from county court records and can be cancelled while in pending status.

### Create county check

 - [POST /county_checks](https://docs.checkrtrust.com/v1/county-checks/post-county-checks.md): Create a new county criminal check for a county jurisdiction, or a state-level criminal check when
county_fips_code is the literal statewide (case-insensitively).

This endpoint supports three mutually exclusive search modes:

{% partial file="/_partials/profile-id-county-precedence.md" /%}

PII search — provide subject identifying information directly:
- first_name (required)
- last_name (required)
- dob (required)
- state (required)
- county_fips_code (required) — 5-digit county FIPS, or statewide for a state-level search

Profile search — reference an existing profile:
- profile_id (required)
- state (required)
- county_fips_code (required) — 5-digit county FIPS, or statewide for a state-level search

Case number search — search by a specific court case number (NC and MN only):
- case_number (required) — letters, numbers, spaces, and hyphens only
- state (required) — NC or MN
- county_fips_code (required) — 5-digit county FIPS

These three modes are mutually exclusive — do not combine case_number with first_name/last_name, dob, profile_id, or lookback_period_in_years in the same request.

### Get county check

 - [GET /county_checks/{county_check_id}](https://docs.checkrtrust.com/v1/county-checks/get-county-check-by-id.md): Get a single county check with a given id.

### Cancel county check

 - [POST /county_checks/{county_check_id}/cancel](https://docs.checkrtrust.com/v1/county-checks/post-county-check-cancel.md): Cancel an existing county check that is in a pending state.

A reason must be provided for the cancellation. Only checks that are
currently in 'pending' status can be cancelled.

## Driver Checks

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

### Get driver checks

 - [GET /driver_checks](https://docs.checkrtrust.com/v1/driver-checks/get-driver-checks.md): Get a set of previously created driver checks

### Create driver check

 - [POST /driver_checks](https://docs.checkrtrust.com/v1/driver-checks/post-driver-checks.md): Create a new driver check.

{% partial file="/_partials/profile-id-pii-mutual-exclusivity-driver-checks.md" /%}

{% partial file="/_partials/driver-check-inline-address-persistence.md" /%}

For motor_vehicle_report checks in Washington (WA), only DPPA purposes employment and insurance are supported.
If your account is configured with a different DPPA purpose, requests for motor_vehicle_report checks in WA will be rejected.
This restriction does not apply to driver_license_status checks.

### Get driver check

 - [GET /driver_checks/{driver_check_id}](https://docs.checkrtrust.com/v1/driver-checks/get-driver-check-by-id.md): Get a previously created driver check with a given id

## Identity Verifications

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.

### Get identity verifications

 - [GET /identity_verifications](https://docs.checkrtrust.com/v1/identity-verifications/get-identity-verifications.md): Get a set of identity verifications

### Create identity verification

 - [POST /identity_verifications](https://docs.checkrtrust.com/v1/identity-verifications/post-identity-verifications.md): Create a new identity verification.

{% partial file="/_partials/profile-id-pii-mutual-exclusivity-reference-id-allowed.md" /%}

### Get identity verification

 - [GET /identity_verifications/{identity_verification_id}](https://docs.checkrtrust.com/v1/identity-verifications/get-identity-verification-by-id.md): Get a single identity verification with a given id

### Download collected document images

 - [GET /identity_verifications/{identity_verification_id}/files](https://docs.checkrtrust.com/v1/identity-verifications/get-identity-verification-files.md): (Document Verification only) Download a ZIP of collected images for the specified identity verification. 
The ZIP contains the following files:
- Doc_Selfie_1_blob.jpg - the selfie image
- documentbackDoc_Back_1_blob.jpg - the document back image
- documentfrontDoc_Front_1_blob.jpg - the document front image

## Profiles

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.

### Get profiles

 - [GET /profiles](https://docs.checkrtrust.com/v1/profiles/get-profiles.md): Get a set of profiles

### Create profile

 - [POST /profiles](https://docs.checkrtrust.com/v1/profiles/post-profiles.md): Create a new profile with personally identifiable information (PII).

The profile can include various identity fields (SSN, email, phone) which are used for identity verification
and record matching in check products. The more identity fields provided, the better
the matching and verification capabilities will be.

### Get profile

 - [GET /profiles/{profile_id}](https://docs.checkrtrust.com/v1/profiles/get-profile-by-id.md): Get a single profile with a given id

## Regulated Adverse Action

Regulated Adverse Action provides two separate endpoints for the FCRA adverse action flow:
Pre-Adverse Action and Adverse Action.

Pre-Adverse Action notifies the subject of a pending adverse decision, delivers a copy of
the report, and provides required FCRA disclosures — giving them an opportunity to dispute
before a final decision is made. This step is optional but must precede a final adverse
action if used.

Adverse Action finalizes the adverse decision and delivers the required notice to the subject.
It may be submitted with or without a prior pre-adverse action.


### Create a pre-adverse action

 - [POST /regulated/pre_adverse_actions](https://docs.checkrtrust.com/v1/regulated-adverse-action/post-regulated-pre-adverse-action.md): Sends a pre-adverse action notification to the subject identified by check_id,
giving them the opportunity to dispute the results of their background check before
a final decision is made regarding their eligibility. This ensures compliance and
fairness in the decision-making process.

This step is optional but must precede a final adverse action if used. Cannot be
submitted after an adverse action has already been taken for this check.

### Get a pre-adverse action

 - [GET /regulated/pre_adverse_actions/{pre_adverse_action_id}](https://docs.checkrtrust.com/v1/regulated-adverse-action/get-regulated-pre-adverse-action-by-id.md): Retrieves a single pre-adverse action record by ID.

### Create an adverse action

 - [POST /regulated/adverse_actions](https://docs.checkrtrust.com/v1/regulated-adverse-action/post-regulated-adverse-action.md): Finalizes an adverse decision against the subject identified by check_id.
Use this when your organization is declining a subject based in whole or in part
on the results of a Checkr Trust background check.

Delivers the required adverse action notice to the subject so they can seek
assistance or initiate a dispute. In the event a dispute is resolved with changes
to the report, Checkr Trust will notify your organization so you can reassess
the subject's eligibility.

May be submitted with or without a prior pre-adverse action.

Including disqualifying_records is optional but strongly recommended — FCRA
requires disclosing which records triggered the adverse decision.

### Get an adverse action

 - [GET /regulated/adverse_actions/{adverse_action_id}](https://docs.checkrtrust.com/v1/regulated-adverse-action/get-regulated-adverse-action-by-id.md): Retrieves a single adverse action record by ID.

## Regulated Instant Criminal Checks

Regulated Instant Criminal Checks provide instant criminal record check results with legal annotation. Results include checks at the record, case, and charge levels indicating compliance with applicable legal rules. A permissible purpose is required for FCRA compliance.

### Get regulated checks

 - [GET /regulated/checks](https://docs.checkrtrust.com/v1/regulated-instant-criminal-checks/get-regulated-checks.md): Get a set of regulated instant criminal checks for the authenticated account.

### Create regulated check

 - [POST /regulated/checks](https://docs.checkrtrust.com/v1/regulated-instant-criminal-checks/post-regulated-checks.md): Create a new regulated criminal background check with legal annotation.

This endpoint performs an instant criminal check and applies legal rules based on
the provided jurisdiction context. Results include legal annotation checks at the
record, case, and charge levels indicating whether items should be included,
investigated, or removed based on applicable regulations.

A permissible purpose must be provided to comply with FCRA requirements.

{% partial file="/_partials/profile-id-pii-regulated-checks.md" /%}

### Get regulated check

 - [GET /regulated/checks/{check_id}](https://docs.checkrtrust.com/v1/regulated-instant-criminal-checks/get-regulated-check-by-id.md): Get a single regulated check with a given id.

## Regulated County Checks

Regulated County Checks provide county-level or statewide criminal background check results for a specific jurisdiction. `county_fips_code` is required. Provide a 5-digit FIPS code for a county-level search, or the literal `statewide` for a state-level search. Results include checks at the record, case, and charge levels indicating compliance with applicable legal rules. A permissible purpose is required for FCRA compliance.

### Create regulated county check

 - [POST /regulated/county_checks](https://docs.checkrtrust.com/v1/regulated-county-checks/post-regulated-county-checks.md): Create a new regulated county criminal check for a specific jurisdiction.

This endpoint initiates a county-level or statewide criminal background check using either
provided PII (personally identifiable information) or an existing profile. Results include
legal annotation checks at the record, case, and charge levels indicating whether items
should be included, investigated, or removed based on applicable regulations.

A permissible purpose must be provided to comply with FCRA requirements.

county_fips_code is required along with the state: provide a 5-digit FIPS code for a
county-level check, or the literal statewide for a state-level check.

{% partial file="/_partials/profile-id-county-precedence.md" /%}

Required fields when providing PII (without profile_id):
- first_name
- last_name
- dob
- state
- county_fips_code
- filter_context
- permissible_purpose

When using a profile_id, state, county_fips_code, filter_context, and permissible_purpose are required.

### Get regulated county check

 - [GET /regulated/county_checks/{regulated_county_check_id}](https://docs.checkrtrust.com/v1/regulated-county-checks/get-regulated-county-check-by-id.md): Get a single regulated county check with a given id.

## Regulated Criminal Reports

Regulated Criminal Reports provide asynchronous criminal record check results with legal annotation. Results are delivered via webhook once processing is complete. A permissible purpose is required for Fair Credit Reporting Act (FCRA) compliance.

### Get regulated criminal reports

 - [GET /regulated/criminal_reports](https://docs.checkrtrust.com/v1/regulated-criminal-reports/get-regulated-criminal-reports.md): Get a set of regulated criminal reports for the authenticated account.

### Create regulated criminal report

 - [POST /regulated/criminal_reports](https://docs.checkrtrust.com/v1/regulated-criminal-reports/post-regulated-criminal-reports.md): Create a new regulated criminal report with legal annotation.

This endpoint creates an asynchronous criminal report that applies legal rules based on
the provided jurisdiction context. Results include legal annotation checks at the
record, case, and charge levels indicating whether items should be included,
investigated, or removed based on applicable regulations.

A permissible purpose must be provided to comply with Fair Credit Reporting Act (FCRA) requirements.

{% partial file="/_partials/profile-id-pii-regulated-criminal-reports.md" /%}

Important Notes:
- Results are NOT returned in the HTTP response (returns 202 Accepted)
- Full results are delivered asynchronously via webhook once processing is complete

### Get regulated criminal report

 - [GET /regulated/criminal_reports/{id}](https://docs.checkrtrust.com/v1/regulated-criminal-reports/get-regulated-criminal-report-by-id.md): Get a single regulated criminal report with a given id.

## Regulated Eviction Checks

Regulated Eviction Checks surface eviction court records. Results are returned synchronously and include case filing details, plaintiff information, and judgement data.

### Get eviction checks

 - [GET /regulated/eviction_checks](https://docs.checkrtrust.com/v1/regulated-eviction-checks/get-eviction-checks.md): Get a list of previously created eviction checks.

### Create eviction check

 - [POST /regulated/eviction_checks](https://docs.checkrtrust.com/v1/regulated-eviction-checks/post-eviction-checks.md): Create a new eviction check.

Eviction checks search court records for eviction filings associated with the provided PII or profile. Results are returned synchronously in the response body.

{% partial file="/_partials/profile-id-pii-eviction-checks.md" /%}

Providing dob is strongly encouraged — it significantly reduces false positives when multiple people share a name.

A permissible purpose must be provided to comply with FCRA requirements.

### Get eviction check

 - [GET /regulated/eviction_checks/{eviction_check_id}](https://docs.checkrtrust.com/v1/regulated-eviction-checks/get-eviction-check-by-id.md): Retrieve a previously created eviction check by its ID.