`Validation`

Full record of a SPEI validation as a JSON:API resource. Returned by `GET /v1/validations/{id}` and synchronous `POST /v1/validate`.

ExtendsJsonApiResourceBase

Properties

Field	Type	Description
`type`*	`string`	JSON:API resource type. Always `validation`.
`id`*	`string (uuid)`	Unique identifier of the validation (UUID v4).
`attributes`*	`object`	Canonical validation data.
`validation_type`	`string`	`direct` for text-parameter requests; `ocr` for receipt image requests.
`is_playground`	`boolean`	Whether the validation ran in playground mode. Playground executions still query Banxico but do not consume quota, emit webhooks, or fire notifications.
`status`	`string`	Lifecycle state: `queued` — enqueued for worker; `processing` — worker handling; `valid` — CEP found and data matches; `not_found` — Banxico queried, transfer not found; `cep_unavailable` — Banxico unreachable; `invalid` — payload rejected post-enqueue; `failed` — terminal failure; `error` — retriable error (Banxico HTTP 5xx).
`banxico_status`	`string \| null`	Banxico-reported status after query. `null` before query.
`processing_time_ms`	`integer \| null`	Milliseconds from enqueue to terminal resolution.
`request_data`	`object`	Literal snapshot of the original request fields.
`created_at`	`string (date-time)`	UTC timestamp of enqueue.
`completed_at`	`string \| null`	UTC timestamp of terminal resolution. `null` while `status` is `queued`/`processing`.
`enqueued_at`	`string \| null`	Timestamp of bus enqueue.
`processing_started_at`	`string \| null`	Timestamp of the first worker XCLAIM.
`expires_at`	`string \| null`	Expiration timestamp for queued validations. After this, the job moves to `failed`.
`etag_version`	`integer \| null`	Incremental version used for `If-None-Match` polling.
`image_path`	`string \| null`	Relative path of the receipt image. OCR only.
`ocr_result`	`object \| null`	Raw OCR result. OCR only.
`ocr_confidence`	`number \| null`	OCR confidence 0–1. OCR only; `null` for `direct`.
`normalized_data`	`object \| null`	Normalized post-OCR fields used to query Banxico.
`normalization_warnings`	`array \| null`	Warnings emitted by the normalization pipeline.
`is_masked`	`boolean \| null`	Whether the receipt has a masked PAN.
`banxico_result`	`object \| null`	Literal payload returned by Banxico CEP.
`error_message`	`string \| null`	Human-readable error message when terminal.
`error_code`	`ValidationErrorCode \| null`	Machine-readable error code when terminal.
`batch_id`	`integer \| null`	Bulk import batch identifier if applicable.
`batch_position`	`integer \| null`	Position within the batch (1-indexed).
`retry_state`	`object`	Full retry cycle state. Always present; if retries are not active, `enabled=false` and policy fields are `null`. Bulk import rows always have `enabled=false`.
`enabled`	`boolean`	Whether the retry cycle is active for this validation.
`max_retries`	`integer \| null`	Configured maximum number of retries. The upper bound depends on the plan (`retry_max_retries`) or the global default `max_retries_cap` (typically 5–10). `null` if `enabled=false`.
`interval_seconds`	`integer \| null`	Interval between retries in seconds (300–86400). `null` if `enabled=false`.
`outcomes`	`array \| null`	Validation outcomes that trigger a retry (`not_found`, `cep_unavailable`, `error`). `null` if `enabled=false`.
`attempts_completed`	`integer`	Number of retries completed so far.
`next_attempt_at`	`TimestampUTC \| null`	Timestamp of the next scheduled retry. `null` if the cycle is in a terminal state or if no retries are active.
`resolved_at`	`TimestampUTC \| null`	Timestamp when a retry resolved the validation to `valid`. `null` if the cycle has not ended by resolution.
`exhausted_at`	`TimestampUTC \| null`	Timestamp when retries were exhausted without resolution. `null` if the cycle has not ended by exhaustion.
`cancelled_at`	`TimestampUTC \| null`	Timestamp when the cycle was explicitly cancelled. `null` if not cancelled.
`terminal_state`	`string \| null`	Terminal state of the cycle: `pending` — active, no final result yet; `resolved` — a retry obtained `valid`; `exhausted` — all attempts used; `cancelled` — cancelled by the user. `null` if the validation has no retry cycle.
`links`	`object`	Related links (JSON:API `links`).
`self`	`string`	URL of the validation.
`cep_xml`	`string \| null`	URL of the CEP in XML format. `null` if `status` is not `valid`.
`cep_pdf`	`string \| null`	URL of the CEP in PDF format. `null` if `status` is not `valid`.

Used in operations

POST /v1/validate
POST /v1/validate-ocr
GET /v1/validations/{id}