# Get bulk upload

Get a single bulk upload by id.

Endpoint: GET /bulk_uploads/{bulk_upload_id}
Version: 1.0
Security: get-bearer-token-using-oauth2

## Security:

  - `get-bearer-token-using-oauth2` (unknown)
    oauth2

## Path parameters:

  - `bulk_upload_id` (string, required)
    the uuid identifying the bulk upload

## Response 200:

  - `200` (unknown)
    OK

## Response 200 fields (application/json):

  - `id` (string, required)
    A universally unique identifier (UUID) in standard format.
    Example: 2b8313e8-4efd-45a1-b578-952b8313e890

  - `product_configuration_name` (string, 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
- `sex_offender_registry` — synchronous Sex Offender Registry checks
    Enum: "instant_criminal", "instant_criminal_regulated", "county_criminal", "county_criminal_regulated", "sex_offender_registry"

  - `state` (string, 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"

  - `row_count` (integer, required)
    Total rows accepted after CSV validation.
    Example: 100

  - `row_count_success` (integer, required)
    Rows that completed successfully.
    Example: 97

  - `row_count_error` (integer, required)
    Rows that failed validation or processing.
    Example: 3

  - `additional_settings` (object, 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).
**Sex Offender Registry** (`sex_offender_registry`): `ruleset_id` / `ruleset_ids`,
optional `provider_name`. Same person (name + DOB) search as Instant Criminal,
narrowed to sex offender registry records.

  - `additional_settings.ruleset_id` (string)
    Identifier of an existing ruleset containing filtering rules. To set up account rulesets, please reach out to your Checkr Account Executive or Customer Success representative to set up the configuration.
    Example: d16e88e6-aacc-4c42-9cd2-58a93dc9d8af

  - `additional_settings.ruleset_ids` (array)
    A list of ruleset identifiers to apply. When both `ruleset_id` and
`ruleset_ids` are provided, they are merged and de-duplicated before applying.

  - `additional_settings.provider_name` (string)
    Optional provider override for Instant Criminal and Sex Offender Registry bulk
uploads only. Single-check Instant Criminal and Sex Offender Registry requests
do not expose this field publicly; prefer account product configuration unless
Checkr directs otherwise.
    Example: tessera

  - `additional_settings.lookback_period_in_years` (integer)
    Optional number of years to look back for criminal records (county products only).
If not provided, the default lookback period configured for the account will be used.
    Example: 7

  - `additional_settings.include_null_date_of_birth` (boolean)
    Optional override for this upload indicating whether county searches include
records with a null date of birth. If omitted, your account's default setting
is used (or `true` if not configured).
    Example: true

  - `additional_settings.permissible_purpose` (string)
    The permissible purpose for requesting this criminal record check, as required by the Fair Credit Reporting Act (FCRA).
This must be provided for all regulated instant criminal checks to ensure compliance with federal regulations.
    Enum: "Court Order", "Consumer Instruction", "Credit Transaction", "Employment", "Insurance Underwriting", "Benefit Eligibility", "Credit Risk", "Consumer Initiated", "Account Review", "Govt Chargecard", "Child Support", "Agency Liquidation"

  - `additional_settings.regulated_user_type` (string)
    Optional regulated user type applied to every row in a regulated bulk upload.
Single regulated check endpoints resolve this from the account's product
configuration and do not accept it on the request body; bulk upload (and
batch runs) allow an explicit upload-level override for filtering exposure.
    Example: regulated

  - `additional_settings.filter_context` (object)
    Context information used to determine which legal rules apply when filtering check results.
Jurisdictions help identify applicable state and local regulations that may affect
which records can be reported.

  - `additional_settings.filter_context.candidate_jurisdiction` (object, required)
    A geographic jurisdiction specified by state, and optionally county and city.

  - `additional_settings.filter_context.candidate_jurisdiction.state` (string)
    A two-letter US state code.
    Example: CA

  - `additional_settings.filter_context.candidate_jurisdiction.county` (string)
    The county name within the state.
    Example: Los Angeles

  - `additional_settings.filter_context.candidate_jurisdiction.city` (string)
    The city name within the jurisdiction.
    Example: San Francisco

  - `additional_settings.filter_context.filter_domain` (string)
    The legal-filtering domain to apply to this check (for example, employment vs. tenancy rules).
This is only needed when your account is configured to allow multiple filter domains.
Most callers do not need to set this — a default domain is applied automatically based on
your account's configuration. When your account does allow choosing a domain per call, only
a limited, pre-approved set of values is accepted; contact Checkr to configure which domains
your account can use.
    Enum: "employment", "long term tenancy", "short term tenancy", "eviction", "other"

  - `created_at` (string, required)
    An ISO 8601 formatted date-time string.
    Example: 2020-01-01T00:00:00Z

  - `errors` (array, required)
    Upload-level validation or processing errors.

  - `errors.code` (string, required)
    Example: validation_error

  - `errors.title` (string, required)
    Human-readable error summary returned to the client. For stored hash errors this
is typically the `detail` message from validation or processing (not a raw
database or stack trace).
    Example: missing required column header

  - `errors.source` (string | null)
    Optional JSON pointer or column name pointing at the problem field.
    Example: state

  - `original_file` (object)
    Metadata for an attached CSV or XLSX file, including a relative download URL.

  - `original_file.filename` (string, required)
    Example: county_batch.csv

  - `original_file.content_type` (string, required)
    Example: text/csv

  - `original_file.byte_size` (integer, required)
    Example: 2048

  - `original_file.human_readable_size` (string, required)
    Example: 2 KB

  - `original_file.download_url` (string, required)
    Path (or absolute URL when the API includes a host) to download the file.
Original CSV uses `/v1/bulk_uploads/{bulk_upload_id}/original`. Result CSV uses
`/v1/bulk_uploads/{bulk_upload_id}/results?format=csv`. Detailed XLSX uses
`/v1/bulk_uploads/{bulk_upload_id}/results?format=xlsx`.
    Example: /v1/bulk_uploads/2b8313e8-b578-45a1-4efd-952b8313e890/original

## Response 401:

  - `401` (unknown)
    Error response

## Response 401 fields (application/json):

  - `code` (string, required)
    A machine-readable error code.
    Example: invalid_request

  - `title` (string, required)
    A human-readable error title.
    Example: Invalid Request

  - `source` (object)
    An object containing references to the source of the error.

  - `source.pointer` (string)
    A JSON Pointer [RFC6901] to the associated entity in the request document.
    Example: /data/attributes/first_name

## Response 404:

  - `404` (unknown)
    Error response

## Response 404 fields (application/json):

  - `code` (string, required)
    A machine-readable error code.
    Example: invalid_request

  - `title` (string, required)
    A human-readable error title.
    Example: Invalid Request

  - `source` (object)
    An object containing references to the source of the error.

  - `source.pointer` (string)
    A JSON Pointer [RFC6901] to the associated entity in the request document.
    Example: /data/attributes/first_name

## Response 500:

  - `500` (unknown)
    Error response

## Response 500 fields (application/json):

  - `code` (string, required)
    A machine-readable error code.
    Example: invalid_request

  - `title` (string, required)
    A human-readable error title.
    Example: Invalid Request

  - `source` (object)
    An object containing references to the source of the error.

  - `source.pointer` (string)
    A JSON Pointer [RFC6901] to the associated entity in the request document.
    Example: /data/attributes/first_name