Skip to content

Bulk Uploads

Bulk Uploads accept a CSV of subjects and run supported check products in batch. Instant Criminal products complete each row synchronously. County Criminal products submit asynchronously and finalize result files once every row is terminal. Regulated products require a FCRA permissible_purpose in upload settings.

Operations

List bulk uploads

Request

List bulk uploads for the authenticated account, newest first.

Security
get-bearer-token-using-oauth2
Query
limitinteger, [ 0 .. 999999 ]

limit the number of records returned

Default:10
skipinteger, [ 0 .. 999999 ]

skip a number of records before returning (for paging)

Default:0
GET
/bulk_uploads
curl -i -X GET \
  'https://api.checkrtrust.com/v1/bulk_uploads?limit=10&skip=0' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

OK

Bodyapplication/json
Array [
idstring, (uuid)(uuid)required

A universally unique identifier (UUID) in standard format.

Example:"2b8313e8-4efd-45a1-b578-952b8313e890"
account_idstring, (uuid)(uuid)required

A universally unique identifier (UUID) in standard format.

Example:"2b8313e8-4efd-45a1-b578-952b8313e890"
product_configuration_idstring, (uuid)(uuid)required

A universally unique identifier (UUID) in standard format.

Example:"2b8313e8-4efd-45a1-b578-952b8313e890"
product_configuration_namestring(bulk_upload_product_name)required

Product configuration name for the upload. The account must have this product enabled. Supported values:

  • instant_criminal — synchronous Instant Criminal checks
  • instant_criminal_regulated — synchronous Regulated Instant Criminal checks
  • county_criminal — asynchronous County Criminal checks
  • county_criminal_regulated — asynchronous Regulated County Criminal checks
Enum:"instant_criminal""instant_criminal_regulated""county_criminal""county_criminal_regulated"
Example:"county_criminal"
statestring(bulk_upload_state)required

Lifecycle state of the bulk upload.

County products may remain in processing while individual rows await provider results (awaiting_results on each item). The upload moves to completed once every row is terminal and result files are generated.

Enum:"submitted""validating""invalid_input""validated""processing""completed""failed"
Example:"processing"
row_countintegerrequired

Total rows accepted after CSV validation.

Example:100
row_count_successintegerrequired

Rows that completed successfully.

Example:97
row_count_errorintegerrequired

Rows that failed validation or processing.

Example:3
additional_settingsobject(bulk_upload_settings)required

Upload-level settings persisted on the bulk upload (additional_settings). Which fields apply depends on product_name. Unknown keys are ignored by the API (strong parameters); only the fields below are accepted.

Send nested multipart fields using Rails bracket notation, for example settings[permissible_purpose]=Employment and settings[filter_context][candidate_jurisdiction][state]=CA.

Instant Criminal (instant_criminal): ruleset_id / ruleset_ids, optional provider_name.

Regulated Instant Criminal (instant_criminal_regulated): same as instant, plus required permissible_purpose, optional regulated_user_type and filter_context.

County Criminal (county_criminal): ruleset_id / ruleset_ids, lookback_period_in_years, include_null_date_of_birth. Per-row jurisdiction (state, county_fips_code) and dob belong in the CSV, not here.

Regulated County Criminal (county_criminal_regulated): county settings plus required permissible_purpose, optional regulated_user_type and filter_context. Per-row dob is required in the CSV (FCRA compliance).

Example:
{
  "lookback_period_in_years": 7
}
created_atstring, (date-time)(datetime)required

An ISO 8601 formatted date-time string.

Example:"2020-01-01T00:00:00Z"
updated_atstring, (date-time)(datetime)required

An ISO 8601 formatted date-time string.

Example:"2020-01-01T00:00:00Z"
errorsArray of objects(bulk_upload_error)required

Upload-level validation or processing errors.

Example:
[]
original_fileobject(bulk_upload_file)

Metadata for an attached CSV or XLSX file, including a relative download URL.

result_fileobject(bulk_upload_file)

Summary CSV of per-row outcomes (present when attached).

detailed_result_fileobject(bulk_upload_file)

Detailed XLSX export (present when attached).

]
Response
[
  {
    "id": "2b8313e8-b578-45a1-4efd-952b8313e890",
    "account_id": "1a7202d7-a467-34b0-3dec-841a7202d789",
    "product_configuration_id": "3c9424f9-c689-56b2-5f0e-a63c9424f901",
    "product_configuration_name": "county_criminal",
    "state": "processing",
    "row_count": 2,
    "row_count_success": 0,
    "row_count_error": 0,
    "additional_settings": { … },
    "created_at": "2026-08-05T12:00:00Z",
    "updated_at": "2026-08-05T12:00:05Z",
    "errors": []
  }
]