Get a single validation

GET https://api.veriko.mx/v1/validations/{id}

Audience: public
Auth: API key
Permission: validations:read

Returns full details of a validation. For async validations in pre-terminal states (queued, processing), includes Retry-After and meta.next_poll_after_seconds to guide polling cadence. Send the ETag in If-None-Match to receive 304 when the state has not changed.

Parameters
Parameter	In	Type	Required	Description
`id` *	path	`string (uuid)`	required	Validation UUID.
`If-None-Match`	header	`string`	optional	Weak ETag received previously. If the row's `etag_version` and `status` are still the same, the server responds 304 Not Modified with no body — useful to avoid transferring the body when the async state hasn't changed since the last poll.

Request

cURLPython•JavaScript•PHP•

curl -X GET 'https://api.veriko.mx/v1/validations/{id}' \
  -H 'Authorization: Bearer mxcep_••••'

Python example — coming soon.

JavaScript example — coming soon.

PHP example — coming soon.

**Response 2xx** `Validation`
Field	Type	Description
`id` *	`string (uuid)`	Unique identifier of the validation (UUID v4).
`type` *	`string`	JSON:API resource type. Always `validation`.
`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` nullable	Banxico-reported status after query. `null` before query.
`processing_time_ms`	`integer \| null` nullable	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` nullable	UTC timestamp of terminal resolution. `null` while `status` is `queued`/`processing`.
`enqueued_at`	`string \| null` nullable	Timestamp of bus enqueue.
`processing_started_at`	`string \| null` nullable	Timestamp of the first worker XCLAIM.
`expires_at`	`string \| null` nullable	Expiration timestamp for queued validations. After this, the job moves to `failed`.
`etag_version`	`integer \| null` nullable	Incremental version used for `If-None-Match` polling.
`image_path`	`string \| null` nullable	Relative path of the receipt image. OCR only.
`ocr_result`	`object \| null` nullable	Raw OCR result. OCR only.
`ocr_confidence`	`number \| null` nullable	OCR confidence 0–1. OCR only; `null` for `direct`.
`normalized_data`	`object \| null` nullable	Normalized post-OCR fields used to query Banxico.
`normalization_warnings`	`array \| null` nullable	Warnings emitted by the normalization pipeline.
`is_masked`	`boolean \| null` nullable	Whether the receipt has a masked PAN.
`banxico_result`	`object \| null` nullable	Literal payload returned by Banxico CEP.
`error_message`	`string \| null` nullable	Human-readable error message when terminal.
`error_code`	`string \| null` nullable	Machine-readable error code when terminal.
`batch_id`	`integer \| null` nullable	Bulk import batch identifier if applicable.
`batch_position`	`integer \| null` nullable	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` nullable	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` nullable	Interval between retries in seconds (300–86400). `null` if `enabled=false`.
`outcomes`	`array \| null` nullable	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`	`union`	Timestamp of the next scheduled retry. `null` if the cycle is in a terminal state or if no retries are active.
`resolved_at`	`union`	Timestamp when a retry resolved the validation to `valid`. `null` if the cycle has not ended by resolution.
`exhausted_at`	`union`	Timestamp when retries were exhausted without resolution. `null` if the cycle has not ended by exhaustion.
`cancelled_at`	`union`	Timestamp when the cycle was explicitly cancelled. `null` if not cancelled.
`terminal_state`	`string \| null` nullable	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.
`links`	`object`	Related links (JSON:API `links`).
`self`	`string`	URL of the validation.
`cep_xml`	`string \| null` nullable	URL of the CEP in XML format. `null` if `status` is not `valid`.
`cep_pdf`	`string \| null` nullable	URL of the CEP in PDF format. `null` if `status` is not `valid`.

**Response status codes** `GET /v1/validations/{id}`
Status	Class	Description	Body
200	`2xx`	Full validation details. In pre-terminal states (`queued`, `processing`) includes `Retry-After` and `meta.next_poll_after_seconds`.	No body
304	`3xx`	The `etag_version` and `status` have not changed since the `If-None-Match` sent. No body. The client must wait `Retry-After` seconds before the next poll.	No body
401	`4xx`	Authentication is required or the provided credentials are invalid.	`ErrorResponse`
403	`4xx`	Permisos insuficientes	`ErrorResponse`
404	`4xx`	Validation not found or does not belong to the authenticated user (`not_found`).	`ErrorResponse`
422	`4xx`	Invalid UUID in path (`invalid_uuid`).	`ErrorResponse`

**Response headers** `200`
Header	Type	Description
`ETag`	`string`	Weak ETag that increments on each state transition. Format: `W/"{etag_version}-{status}"`. Send it in `If-None-Match` to receive 304 if nothing changed.
`Retry-After`	`integer`	Seconds to wait before the next poll. Only present in `queued` and `processing` states.

**Errors from `GET /v1/validations/{id}`**
Status	Code	Detail
401	`unauthorized`	Invalid or missing authentication credentials. Envelope meta.request_id `c4d5e6f7a8b9`
403	`forbidden`	You do not have permission to access this resource. Envelope meta.request_id `d5e6f7a8b9c0`