Skip to content

Checkr Trust API (1.0)

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

Download OpenAPI description
v1.json
v1.yaml
Overview
URL
https://checkrtrust.com
API Development Team
checkr-trust@checkr.com
License
Proprietary
Languages
Servers
Mock server
https://api.docs.checkrtrust.com/_mock/v1
Checkr Trust API
https://api.checkrtrust.com/v1

Accounts

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

Operations

Instant Checks

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

Operations

Criminal Checks

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

Operations

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.

Operations

Driver Checks

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

Operations

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.

Operations

Create identity verification

Request

Create a new identity verification

Security
get-bearer-token-using-oauth2
Query
includeArray of strings

include related resources in the response

Examples:

Including the profile parameter will embed the full profile object in place of the profile_id

include=profile
Bodyapplication/jsonrequired

The request body for creating a new identity verification

One of:

the request to create a new identity verification from set of PII

Any of:

The object must have DOB.

idv_typestring(idv_type)required

The type of identity verification to be done.

Enum ValueDescription
pii_validation

When requesting pii_validation, the result will be returned immediately.

document_verification

When requesting document_verification, the result will be returned asynchronously through a pre-defined webhook.

personal_identity_records

When requesting personal_identity_records, enriched identity information will be returned immediately.

Example: "pii_validation"
first_namestringrequired

The first name of the person

Example: "JOHN"
middle_namestring

For document verification, the middle name of the person.

last_namestringrequired

The last name of the person

Example: "SMITH"
dobstring= 8 characters\d{8}required

Date of birth in the form YYYYMMDD. Must be a valid date and cannot be in the future. If invalid, the API returns a 400 with a validation_error pointing to /dob.

Example: "19950401"
phonestring(phone_string)^\+[1-9]\d{1,14}$

A phone number in the form +[country code][number including area code]. (E.164 format). Please note that U.S. phone numbers have a country code of "1" so all U.S. phone numbers ought to start with "+1".

emailstring(email)(email_string)

An email address.

Example: "j.doe@example.com"
ssnstring(ssn_string)^\d{3}-?\d{2}-?\d{4}$

A US Social Security Number in XXX-XX-XXXX format. Hyphens are optional.

addressobject(address)

A physical address in the United States.

address.​streetstringrequired

The street address, including house/building number and street name. Apartment/unit numbers may be included but are not used for matching.

Example: "123 Main St"
address.​citystringrequired

The name of the city or municipality.

Example: "Frankfort"
address.​statestring(state_code)^[A-Z]{2}$required

The two-letter US state code where the address is located.

address.​zip_codestring(zip_code)^\d{5}(-\d{4})?$required

US Postal Service ZIP code (5-digit or 9-digit ZIP+4 format).

address.​countrystring(country_code)^[A-Z]{2}$

The two-letter country code, typically "US" for United States addresses.

reference_idstring(reference_id)^[a-zA-Z0-9_-]{1,64}$

A reference identifier for linking related records. Limited to 64 alphanumeric characters, underscores, and hyphens.

send_messageboolean

For document verification, whether the end user should receive an SMS with the collection link to the provided phone number. Defaults to false if not provided.

Default false
skip_selfieboolean

For document verification, whether we should skip collecting and verifying a selfie. Defaults to false.

Default false
curl -i -X POST \
  'https://api.docs.checkrtrust.com/_mock/v1/identity_verifications?include=string' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "first_name": "JOHN",
    "last_name": "SMITH",
    "idv_type": "pii_validation",
    "email": "j.doe@example.com"
  }'

Responses

Created. When the product has usage limits configured, the response includes X-RateLimit-Limit, X-RateLimit-Remaining, and optionally X-RateLimit-Expires.

Bodyapplication/json
idstring(uuid)(uuid)required

the UUID of the identity verification.

created_atstring(date-time)(datetime)required

An ISO 8601 formatted date-time string.

resultsidv_result_pii_validation (object) or idv_result_document_verification_initial (object) or idv_result_personal_identity_records (object)required

The structure of results depends on the value of idv_type.

One of:

The structure of results depends on the value of idv_type.

results.​attribute_match_scoresobject(attribute_match_scores)

attribute match scores

results.​attribute_match_scores.​first_nameinteger(attribute_match_score)

0 if an attribute does not match, 100 if it matches

Enum0100
results.​attribute_match_scores.​last_nameinteger(attribute_match_score)

0 if an attribute does not match, 100 if it matches

Enum0100
results.​attribute_match_scores.​dobinteger(attribute_match_score)

0 if an attribute does not match, 100 if it matches

Enum0100
results.​attribute_match_scores.​phoneinteger(attribute_match_score)

0 if an attribute does not match, 100 if it matches

Enum0100
results.​attribute_match_scores.​emailinteger(attribute_match_score)

0 if an attribute does not match, 100 if it matches

Enum0100
results.​attribute_match_scores.​addressinteger(attribute_match_score)

0 if an attribute does not match, 100 if it matches

Enum0100
results.​attribute_match_scores.​cityinteger(attribute_match_score)

0 if an attribute does not match, 100 if it matches

Enum0100
results.​attribute_match_scores.​stateinteger(attribute_match_score)

0 if an attribute does not match, 100 if it matches

Enum0100
results.​attribute_match_scores.​zip_codeinteger(attribute_match_score)

0 if an attribute does not match, 100 if it matches

Enum0100
results.​attribute_match_scores.​ssninteger(attribute_match_score)

0 if an attribute does not match, 100 if it matches

Enum0100
results.​overall_match_scoreinteger(attribute_match_score_overall)

0 if no attributes match, 50 if some attributes match, 100 if all attributes match

Enum050100
results.​result_contextArray of objects(idv_result_context_item)
results.​result_context[].​codestring

A stable code for the reason or context

Example: "CT-0195"
results.​result_context[].​titlestring

A user-friendly description of the reason or context

Example: "Address is correlated with a past address"
results.​result_context[].​categorystring

Category derived from the provider reason code.

Enum"informational""rejection""unknown"
Example: "informational"
profile_idstring(uuid)(uuid)

the UUID of the profile.

profileobject(profile)

A profile containing personal information used for checks and verifications.

profile.​idstring(uuid)(profile_id)

Identifier of an existing profile containing search criteria.

profile.​first_namestring

The first name of the person.

profile.​middle_namestring

The middle name of the person. Can be null if not provided.

profile.​last_namestring

The last name of the person.

profile.​dobstring= 8 characters\d{8}

Date of birth in the form YYYYMMDD. Must be a valid date and cannot be in the future. If invalid, the API returns a 400 with a validation_error pointing to /dob.

Example: "19950401"
profile.​phonestring(phone_string)^\+[1-9]\d{1,14}$

A phone number in the form +[country code][number including area code]. (E.164 format)

profile.​emailstring(email)(email_string)

An email address.

profile.​ssnstring(ssn_string)^\d{3}-?\d{2}-?\d{4}$

A US Social Security Number in XXX-XX-XXXX format. Hyphens are optional.

profile.​addressobject(address)

A physical address in the United States.

profile.​address.​streetstringrequired

The street address, including house/building number and street name. Apartment/unit numbers may be included but are not used for matching.

Example: "123 Main St"
profile.​address.​citystringrequired

The name of the city or municipality.

Example: "Frankfort"
profile.​address.​statestring(state_code)^[A-Z]{2}$required

The two-letter US state code where the address is located.

profile.​address.​zip_codestring(zip_code)^\d{5}(-\d{4})?$required

US Postal Service ZIP code (5-digit or 9-digit ZIP+4 format).

profile.​address.​countrystring(country_code)^[A-Z]{2}$

The two-letter country code, typically "US" for United States addresses.

profile.​custom_idstring(custom_id_string)^[a-zA-Z0-9_-]{1,64}$

An identifier of your choice, if you wish to use one. Limited to 64 alphanumeric characters, underscores, and hyphens.

profile.​driver_license_statestring(state_code)^[A-Z]{2}$

A two-letter US state code.

profile.​driver_license_numberstring

The driver license number. Format dependent on State.

Example: "D1234567"
idv_typestring(idv_type)required

The type of identity verification to be done.

Enum ValueDescription
pii_validation

When requesting pii_validation, the result will be returned immediately.

document_verification

When requesting document_verification, the result will be returned asynchronously through a pre-defined webhook.

personal_identity_records

When requesting personal_identity_records, enriched identity information will be returned immediately.

reference_idstring(reference_id)^[a-zA-Z0-9_-]{1,64}$

A reference identifier for linking related records. Limited to 64 alphanumeric characters, underscores, and hyphens.

Response
application/json
{
  "id": "2b8313e8-4efd-45a1-b578-952b8313e890",
  "created_at": "2020-01-01T00:00:00Z",
  "results": {
    "attribute_match_scores": { … },
    "overall_match_score": 50,
    "result_context": [ … ]
  },
  "profile_id": "2b8313e8-4efd-45a1-b578-952b8313e890",
  "profile": {
    "id": "2b8313e8-4efd-45a1-b578-952b8313e890",
    "first_name": "string",
    "middle_name": "string",
    "last_name": "string",
    "dob": "19950401",
    "phone": "+14155552671",
    "email": "john.doe@example.com",
    "ssn": "123-45-6789",
    "address": { … },
    "custom_id": "my-custom-id-123",
    "driver_license_state": "CA",
    "driver_license_number": "D1234567"
  },
  "idv_type": "pii_validation",
  "reference_id": "ref-123"
}

Callbacks

Callback (webhook) triggered when document verification is completed.
post

Get identity verification

Request

Get a single identity verification with a given id

Security
get-bearer-token-using-oauth2
Path
identity_verification_idstring(uuid)required

the uuid identifying the identity verification

Example: 2b8313e8-4efd-45a1-b578-952b8313e890
Query
includeArray of strings

include related resources in the response

curl -i -X GET \
  'https://api.docs.checkrtrust.com/_mock/v1/identity_verifications/2b8313e8-4efd-45a1-b578-952b8313e890?include=string' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

OK

Bodyapplication/json
One of:
profile_idstring(uuid)(profile_id)required

Identifier of an existing profile containing search criteria.

idstring(uuid)(uuid)

A universally unique identifier (UUID) in standard format.

created_atstring(date-time)(datetime)

An ISO 8601 formatted date-time string.

completed_atstring(date-time)(datetime)

An ISO 8601 formatted date-time string.

resultsidv_result_pii_validation (object) or idv_result_document_verification (object) or idv_result_personal_identity_records (object)

The structure of results depends on the value of idv_type.

One of:

The structure of results depends on the value of idv_type.

results.​attribute_match_scoresobject(attribute_match_scores)

attribute match scores

results.​attribute_match_scores.​first_nameinteger(attribute_match_score)

0 if an attribute does not match, 100 if it matches

Enum0100
results.​attribute_match_scores.​last_nameinteger(attribute_match_score)

0 if an attribute does not match, 100 if it matches

Enum0100
results.​attribute_match_scores.​dobinteger(attribute_match_score)

0 if an attribute does not match, 100 if it matches

Enum0100
results.​attribute_match_scores.​phoneinteger(attribute_match_score)

0 if an attribute does not match, 100 if it matches

Enum0100
results.​attribute_match_scores.​emailinteger(attribute_match_score)

0 if an attribute does not match, 100 if it matches

Enum0100
results.​attribute_match_scores.​addressinteger(attribute_match_score)

0 if an attribute does not match, 100 if it matches

Enum0100
results.​attribute_match_scores.​cityinteger(attribute_match_score)

0 if an attribute does not match, 100 if it matches

Enum0100
results.​attribute_match_scores.​stateinteger(attribute_match_score)

0 if an attribute does not match, 100 if it matches

Enum0100
results.​attribute_match_scores.​zip_codeinteger(attribute_match_score)

0 if an attribute does not match, 100 if it matches

Enum0100
results.​attribute_match_scores.​ssninteger(attribute_match_score)

0 if an attribute does not match, 100 if it matches

Enum0100
results.​overall_match_scoreinteger(attribute_match_score_overall)

0 if no attributes match, 50 if some attributes match, 100 if all attributes match

Enum050100
results.​result_contextArray of objects(idv_result_context_item)
results.​result_context[].​codestring

A stable code for the reason or context

Example: "CT-0195"
results.​result_context[].​titlestring

A user-friendly description of the reason or context

Example: "Address is correlated with a past address"
results.​result_context[].​categorystring

Category derived from the provider reason code.

Enum"informational""rejection""unknown"
Example: "informational"
idv_typestring(idv_type)

The type of identity verification to be done.

Enum ValueDescription
pii_validation

When requesting pii_validation, the result will be returned immediately.

document_verification

When requesting document_verification, the result will be returned asynchronously through a pre-defined webhook.

personal_identity_records

When requesting personal_identity_records, enriched identity information will be returned immediately.

reference_idstring(reference_id)^[a-zA-Z0-9_-]{1,64}$

A reference identifier for linking related records. Limited to 64 alphanumeric characters, underscores, and hyphens.

Response
application/json
{
  "profile_id": "2b8313e8-4efd-45a1-b578-952b8313e890",
  "id": "2b8313e8-4efd-45a1-b578-952b8313e890",
  "created_at": "2020-01-01T00:00:00Z",
  "completed_at": "2020-01-01T00:00:00Z",
  "results": {
    "attribute_match_scores": { … },
    "overall_match_score": 50,
    "result_context": [ … ]
  },
  "idv_type": "pii_validation",
  "reference_id": "ref-123"
}

Download collected document images

Request

(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
Security
get-bearer-token-using-oauth2
Path
identity_verification_idstring(uuid)required

the uuid identifying the identity verification

Example: 2b8313e8-4efd-45a1-b578-952b8313e890
curl -i -X GET \
  https://api.docs.checkrtrust.com/_mock/v1/identity_verifications/2b8313e8-4efd-45a1-b578-952b8313e890/files \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

ZIP file

Bodyapplication/zip
string(binary)
Response
No content

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.

Operations

Regulated Checks

Regulated 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.

Operations

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.

Operations