List validations

GET https://api.veriko.mx/v1/validations

List validations

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

Returns a paginated list of the authenticated user's validations. All filters are additive: status (single value or CSV list), type, date_from/date_to, search (tracking key, numeric reference, issuing or receiving bank), bank, amount_min/amount_max, with_deleted, playground, batch_id and retry_state. To fetch a single row with its full retry_state and ETag use GET /v1/validations/{id}; to download the CEP for a valid row use GET /v1/validations/{id}/cep.

Parameters
Parameter	In	Type	Required	Description
`amount_max`	query	`number (float)`	optional	Inclusive maximum amount. Compared against the validation's `monto` (normalized_data, falling back to request_data). Independent of `amount_min`.
`amount_min`	query	`number (float)`	optional	Inclusive minimum amount. Compared against the validation's `monto` (normalized_data, falling back to request_data). Independent of `amount_max`.
`bank`	query	`string`	optional	Filter by the bank's 3-digit SPEI code (receiver or sender). Digits only, max 5 characters; any other value is ignored.
`batch_id`	query	`integer`	optional	Filter to validations generated by a bulk import job (`POST /v1/validations/imports/{id}/commit`). Used by the post-commit detail view.
`date_from`	query	`string (date)`	optional	Inclusive start date (YYYY-MM-DD). Truncated to 10 characters.
`date_to`	query	`string (date)`	optional	Inclusive end date (YYYY-MM-DD). Truncated to 10 characters.
`page`	query	`integer`	optional	Page number. Minimum 1. Default: `1`
`per_page`	query	`integer`	optional	Items per page (1–50). The controller clamps out-of-range values. Default: `10`
`playground`	query	`string`	optional	When exactly `'1'`, restricts the listing to sandbox validations. Any other value is ignored (default: production only).
`retry_state`	query	`string`	optional	Filter by automatic retry cycle status: `pending` = in progress; `resolved` = resolved via retry; `exhausted` = attempts exhausted; `cancelled` = manually cancelled. Values outside the allowlist return 422 `invalid_filter`.
`search`	query	`string`	optional	Case-insensitive free-text search over the validation's JSON content (request_data + normalized_data): tracking key, numeric reference, amount, account, and the resolved bank/beneficiary names (e.g. `scotiabank` finds "SCOTIABANK") when present in the normalized data. Truncated to 100 characters; `%` and `_` are treated as literals (not wildcards).
`status`	query	`string`	optional	Filter by granular status. Accepts a single value or a comma-separated list (CSV), e.g. `not_found,cep_unavailable,invalid,failed,error` for the "Not confirmed" segment. Each token must belong to the allowlist: `queued`, `processing`, `valid`, `not_found`, `cep_unavailable`, `invalid`, `failed`, `error`; tokens outside the allowlist are ignored. The filter is honored literally in both cases (`status = ?` for a single value, `status IN (...)` for CSV), so the "In progress" (`processing`) and "Queued" (`queued`) segments stay distinct. For the combined pre-terminal set, send `status=queued,processing`.
`type`	query	`string`	optional	Filter by validation type (`direct` or `ocr`).
`with_deleted`	query	`string`	optional	Tri-state full-visibility: omit = all (active + soft-deleted); `'1'` = soft-deleted only; `'0'` = active only. Convention shared with admin panels.

Request

cURLPython•JavaScript•PHP•

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

Python example — coming soon.

JavaScript example — coming soon.

PHP example — coming soon.

**Response 200** `ValidationListItem` — Paginated list of validations with pagination metadata.
Field	Type	Description
`id`	`string (uuid)`	Unique identifier of the validation (UUID v4).
`type`	`string`	JSON:API resource type. Always `validation`.
`validation_type`	`string`	Validation type: `direct` for text parameters, `ocr` for receipt image.
`status`	`string`	Result status. See `Validation.attributes.status` for the full description of each value.
`fecha`	`string (date)`	Transfer date (YYYY-MM-DD).
`monto`	`number (double)`	Transfer amount in Mexican pesos (MXN).
`clave_rastreo`	`string`	SPEI tracking key.
`emisor`	`string`	Sending bank of the transfer.
`receptor`	`string`	Receiving bank of the transfer.
`playground`	`boolean`	Whether the validation was executed in sandbox mode.
`created_at`	`string (date-time)`	ISO 8601 timestamp in UTC with explicit `Z` suffix. Example: `"2026-05-01T05:14:38Z"`. Every datetime field uses this shape. The descriptor at `meta.datetime` makes the contract runtime-assertable.
`completed_at`	`union`	Timestamp when the validation completed. `null` while status is `queued` or `processing`.
`deleted_at`	`union`	Soft-delete timestamp. `null` if the validation has not been deleted.
`is_deleted`	`boolean`	`true` if and only if `deleted_at` is set; convenience field for UI filtering.
`retry_state`	`object`	Compact retry cycle state. Policy fields (`max_retries`, `interval_seconds`, `outcomes`) are always `null` in this view; use `GET /v1/validations/{id}` for the full state.
`enabled`	`boolean`	Whether the retry cycle is active for this validation.
`max_retries`	`integer \| null` nullable	Always `null` in the compact shape. See `RetryStateFull` for the value.
`interval_seconds`	`integer \| null` nullable	Always `null` in the compact shape. See `RetryStateFull` for the value.
`outcomes`	`array \| null` nullable	Always `null` in the compact shape. See `RetryStateFull` for the value.
`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.

**Response status codes** `GET /v1/validations`
Status	Class	Description	Body
200	`2xx`	Paginated list of validations with pagination metadata.	No body
401	`4xx`	Authentication is required or the provided credentials are invalid.	`ErrorResponse`
422	`4xx`	Invalid value for `retry_state` (code `invalid_filter`).	`ErrorResponse`

**Errors from `GET /v1/validations`**
Status	Code	Detail
401	`unauthorized`	Invalid or missing authentication credentials. Envelope meta.request_id `c4d5e6f7a8b9`