Skip to content

Create bulk upload

Request

Upload a CSV of subjects and start asynchronous validation for a supported check product.

Supported product_name values:

  • instant_criminal
  • instant_criminal_regulated (requires settings.permissible_purpose; per-row dob)
  • county_criminal (CSV rows must include state, county_fips_code, and dob)
  • county_criminal_regulated (same county CSV columns; plus settings.permissible_purpose; per-row dob)

CSV column requirements, header aliases, and example rows for each product are documented on the request body schema below.

On success the upload is created in submitted / moves through validation. Instant products complete each row when the check factory returns. County products submit provider searches asynchronously; the upload stays in processing until every row is terminal, then result files are generated.

County rows are also subject to the same pilot jurisdiction blocks and fulfillment submission caps as single county checks.

Security
get-bearer-token-using-oauth2
Bodymultipart/form-datarequired
product_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"
original_filestring, (binary)required

CSV file (.csv). Max size is configured server-side.

settingsobject(bulk_upload_settings)

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

POST
/bulk_uploads
curl -i -X POST \
  https://api.checkrtrust.com/v1/bulk_uploads \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: multipart/form-data' \
  -F product_name=county_criminal \
  -F original_file=string \
  -F 'settings={"ruleset_id":"d16e88e6-aacc-4c42-9cd2-58a93dc9d8af","ruleset_ids":["d16e88e6-aacc-4c42-9cd2-58a93dc9d8af"],"provider_name":"tessera","lookback_period_in_years":7,"include_null_date_of_birth":true,"permissible_purpose":"Employment","regulated_user_type":"regulated","filter_context":{"candidate_jurisdiction":{"state":"CA","county":"Los Angeles","city":"San Francisco"},"decider_jurisdiction":{"state":"CA","county":"Los Angeles","city":"San Francisco"},"property_jurisdiction":{"state":"CA","county":"Los Angeles","city":"San Francisco"},"filter_domain":"employment"}}'

Responses

Created

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": []
}