Skip to content

Get bulk upload

Request

Get a single bulk upload by id.

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

the uuid identifying the bulk upload

Example:2b8313e8-b578-45a1-4efd-952b8313e890
GET
/bulk_uploads/{bulk_upload_id}
curl -i -X GET \
  https://api.checkrtrust.com/v1/bulk_uploads/2b8313e8-b578-45a1-4efd-952b8313e890 \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

OK

Bodyapplication/json
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": {
    "lookback_period_in_years": 7
  },
  "created_at": "2026-08-05T12:00:00Z",
  "updated_at": "2026-08-05T12:00:05Z",
  "errors": []
}