`ValidationImportJob`

JSON:API resource for a bulk validation import job and its execution state.

ExtendsJsonApiResourceBase

Properties

Field	Type	Description
`type`	`string`	JSON:API resource type. Always `validation_import`.
`id`	`string`	Numeric job ID as a string (JSON:API convention).
`attributes`	`object`	Import job data.
`status`	`string`	Current state — `pending`: Received and awaiting parsing; `parsing`: Extracting and validating rows; `preview_ready`: Parsing complete and awaiting review; `committing`: Processing the approved rows; `completed`: All rows processed; `failed`: Unrecoverable error; `cancelled`: Job cancelled by the user.
`upload_type`	`string`	Input mode: `text` for structured or free-form data; `images` for receipt images.
`file_format`	`string`	Format of the uploaded file (`csv`, `xls`, `xlsx`, `txt`, `json`, `zip_text`, or `zip_images`).
`parse_mode`	`string`	File reading mode — `template`: Follows the canonical headers; `free`: Free-form, the system infers the structure.
`total_rows`	`integer`	Number of rows extracted from the file.
`plan_cap`	`object`	The plan's bulk-import cap (`bulk_validations_max`, per batch) compared against `total_rows`, to warn in the preview before confirming actually rejects the batch with `422` `plan_cap_exceeded`.
`max`	`integer`	The active plan's rows-per-batch cap.
`exceeded`	`boolean`	`true` when `total_rows` already exceeds `max`.
`valid_count`	`integer`	Number of rows without errors, ready to be committed.
`correctable_count`	`integer`	Number of rows with errors that can be corrected.
`fatal_count`	`integer`	Number of rows that cannot be processed with their current data.
`duplicate_count`	`integer`	Number of rows detected as duplicates within the job.
`dispatched_count`	`integer`	Rows submitted for validation after job confirmation.
`completed_valid_count`	`integer`	Rows whose validation ended in `valid`.
`completed_not_found_count`	`integer`	Rows whose validation ended in `not_found`.
`completed_invalid_count`	`integer`	Rows whose validation ended in `invalid`.
`completed_cep_unavailable_count`	`integer`	Rows whose validation ended in `cep_unavailable`.
`completed_returned_count`	`integer`	Rows whose validation ended in `returned` (the transfer was settled and later returned).
`completed_error_count`	`integer`	Rows whose validation ended in `error` or `failed`.
`skipped_count`	`integer`	Number of rows skipped while the job was running.
`ocr_invoked`	`boolean`	`true` when OCR was used during parsing. Only relevant when `upload_type` is `images`.
`ocr_input_tokens`	`integer`	Input tokens accumulated by job OCR. It is `0` when `ocr_invoked` is `false`.
`ocr_output_tokens`	`integer`	Output tokens accumulated by job OCR. It is `0` when `ocr_invoked` is `false`.
`error_code`	`string \| null`	Stable code of the job failure. `null` when it did not end in `failed`.
`error_summary`	`string \| null`	Readable summary of the job failure. `null` when it did not end in `failed`.
`created_at`	`string (date-time)`	ISO 8601 timestamp in UTC with an explicit `Z` suffix; for example, `"2026-05-01T05:14:38Z"`. The `_at`, `_end`, `_start`, and `_date` fields follow this format. `meta.datetime` describes the same contract in the response.
`parsed_at`	`string \| null`	Date and time when the file reading finished, in ISO 8601 UTC. `null` while it has not finished.
`committed_at`	`string \| null`	Date and time when the commit started, in ISO 8601 UTC. `null` while it has not been committed.
`completed_at`	`string \| null`	Date and time of completion, in ISO 8601 UTC. `null` while it has not finished.

Used in operations

GET /v1/validations/imports/{id}
GET /v1/validations/imports/{id}/preview