Get a single validation

GEThttps://api.veriko.mx/v1/validations/{id}

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

Returns the full detail of a validation, and is also the point where an asynchronous validation's verdict is collected. While the validation has not reached a terminal state — queued or processing — the response carries the Retry-After header and meta.next_poll_after_seconds, which mark when asking again is worth it. Sending back the received ETag in If-None-Match returns 304 when the state has not changed, so polling does not download the same thing twice; the full mechanism is covered in conditional caching.

Parameters
Parameter	In	Type	Required	Description
`id`*	path	`string (uuid)`	required	Validation UUID.
`If-None-Match`	header	`string`	optional	ETag received in previous requests. If the data has not changed and `etag_version` is still the same, the server responds `304 Not Modified` (no body) — avoids receiving the data again when the resource state has NOT changed. e.g. `W/"3-processing"`

Request

cURLPython•JavaScript•PHP•

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

Python example — coming soon.

JavaScript example — coming soon.

PHP example — coming soon.

**Response 2xx**`Validation`
Field	Type	Description
`type`*	`string`	JSON:API resource type. Always `validation`. e.g. `validation`
`id`*	`string (uuid)`	Unique identifier of the validation (UUID v4). e.g. `3fa85f64-5717-4562-b3fc-2c963f66afa6`
`attributes`*	`object`	Canonical validation data.
`validation_type`	`string`	`direct` for text-parameter requests; `ocr` for receipt image requests. e.g. `direct`
`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. e.g. `false`
`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). e.g. `valid`
`banxico_status`	`string \| null`nullable	Banxico-reported status after query. `null` before query. e.g. `valid`
`processing_time_ms`	`integer \| null`nullable	Milliseconds from enqueue to terminal resolution. e.g. `1320`
`request_data`	`object`	Literal snapshot of the original request fields.
`created_at`	`string (date-time)`	UTC timestamp of enqueue. e.g. `2025-03-15T14:22:10Z`
`completed_at`	`string \| null`nullable	UTC timestamp of terminal resolution. `null` while `status` is `queued`/`processing`. e.g. `2025-03-15T14:22:11Z`
`enqueued_at`	`string \| null`nullable	Timestamp of bus enqueue. e.g. `2026-04-30T10:15:00Z`
`processing_started_at`	`string \| null`nullable	Timestamp of the first worker XCLAIM. e.g. `2026-04-30T10:15:00Z`
`expires_at`	`string \| null`nullable	Expiration timestamp for queued validations. After this, the job moves to `failed`. e.g. `2026-04-30T10:15:00Z`
`etag_version`	`integer \| null`nullable	Incremental version used for `If-None-Match` polling. e.g. `1`
`image_path`	`string \| null`nullable	Relative path of the receipt image. OCR only. e.g. `ocr/2026/04/a1b2c3d4.jpg`
`ocr_result`	`object \| null`nullable	Raw OCR result. OCR only.
`ocr_confidence`	`number \| null`nullable	OCR confidence 0–1. OCR only; `null` for `direct`. e.g. `0.94`
`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. e.g. `Banxico no respondió tras tres intentos.`
`error_code`	`ValidationErrorCode \| null`	Machine-readable error code when terminal.
`batch_id`	`integer \| null`nullable	Bulk import batch identifier if applicable. e.g. `318`
`batch_position`	`integer \| null`nullable	Position within the batch (1-indexed). e.g. `12`
`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. e.g. `true`
`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`. e.g. `3`
`interval_seconds`	`integer \| null`nullable	Interval between retries in seconds (300–86400). `null` if `enabled=false`. e.g. `600`
`outcomes`	`array \| null`nullable	Validation outcomes that trigger a retry (`not_found`, `cep_unavailable`, `error`). `null` if `enabled=false`. e.g. `["not_found","cep_unavailable","error"]`
`attempts_completed`	`integer`	Number of retries completed so far. e.g. `1`
`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`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. `null` if the validation has no retry cycle. e.g. `pending`
`links`	`object`	Related links (JSON:API `links`).
`self`	`string`	URL of the validation. e.g. `/v1/validations/3fa85f64-5717-4562-b3fc-2c963f66afa6`
`cep_xml`	`string \| null`nullable	URL of the CEP in XML format. `null` if `status` is not `valid`. e.g. `/v1/validations/a1b2c3d4-e5f6-7890-abcd-ef0123456789/cep.xml`
`cep_pdf`	`string \| null`nullable	URL of the CEP in PDF format. `null` if `status` is not `valid`. e.g. `/v1/validations/a1b2c3d4-e5f6-7890-abcd-ef0123456789/cep.pdf`

**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`	Insufficient permissions.	`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	Example
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`