Validation statistics for the user

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

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

Returns aggregated counts of the authenticated user's validations: total, valid, not_found, cep_unavailable, error, pending, deleted, and other, plus a by_type breakdown (direct/ocr) and a by_status breakdown by lifecycle status (queued/processing/valid/…). The other bucket is the remainder after subtracting the five named statuses (in practice, invalid rows). The top-level buckets count by banxico_status (verdict); by_status counts by the status column (lifecycle) — the same axis the table filters on. Honors the same filter set as GET /v1/validations (date_from, date_to, type, search, with_deleted, playground, batch_id, bank, amount_min/amount_max). The status filter is accepted but ignored at the repo layer — each KPI carries its own target.

Parameters
Parameter	In	Type	Required	Description
`amount_max`	query	`number (float)`	optional	Inclusive maximum amount (normalized_data, fallback request_data).
`amount_min`	query	`number (float)`	optional	Inclusive minimum amount (normalized_data, fallback request_data).
`bank`	query	`string`	optional	Restricts the counters to the bank's 3-digit SPEI code (receiver or sender). Digits only, max 5 characters.
`batch_id`	query	`integer`	optional	Restricts the counters to the batch of a bulk import.
`date_from`	query	`string (date)`	optional	Inclusive start date (YYYY-MM-DD).
`date_to`	query	`string (date)`	optional	Inclusive end date (YYYY-MM-DD).
`playground`	query	`string`	optional	When set to `'1'`, restricts results to sandbox.
`search`	query	`string`	optional	Search by tracking key, numeric reference, sender, and receiver.
`type`	query	`string`	optional	Filter by validation type.
`with_deleted`	query	`string`	optional	Tri-state: omit = all; `'1'` = deleted only; `'0'` = active only.

Request

cURLPython•JavaScript•PHP•

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

Python example — coming soon.

JavaScript example — coming soon.

PHP example — coming soon.

**Response 200** `ValidationStats` — Aggregated validation statistics for the user.
Field	Type	Description
`type`	`string`	JSON:API resource type (always `validation_stats`).
`attributes`	`object`	Aggregated counters of the user's validations (matching the filters). The top-level buckets count by `banxico_status` (verdict); `by_status` breaks down by the `status` column (lifecycle).
`total`	`integer`	Total count of the user's validations matching the filters. Counts every row regardless of Banxico status.
`valid`	`integer`	Subset of the total with `banxico_status='valid'` (transfer confirmed).
`not_found`	`integer`	Subset of the total with `banxico_status='not_found'`.
`cep_unavailable`	`integer`	Subset of the total with `banxico_status='cep_unavailable'` (the Banxico CEP service was unavailable at validation time).
`error`	`integer`	Subset of the total with `banxico_status='error'` (Banxico error, e.g. HTTP 5xx or network failure).
`pending`	`integer`	Subset of the total with `banxico_status='pending'`: async validations still queued or processing, with no CEP result yet.
`deleted`	`integer`	Count of the user's soft-deleted validations (matching the same filters).
`other`	`integer`	Remainder of the total after subtracting `valid`, `not_found`, `cep_unavailable`, `error` and `pending`. In practice this is the `invalid` count. Computed as `max(0, total - valid - not_found - cep_unavailable - error - pending)`.
`by_type`	`object`	Breakdown by validation type. `direct + ocr` always sums to `total`.
`direct` *	`integer`	Direct validations (by CLABE/card/phone fields).
`ocr` *	`integer`	OCR validations (from a receipt image).
`by_status`	`object`	Breakdown by lifecycle status (the `status` column: `queued` / `processing` / `valid` / `not_found` / `cep_unavailable` / `invalid` / `failed` / `error`). This is the SAME axis the validations table filters on (unlike `valid` / `not_found` / `cep_unavailable` / `error` / `pending` above, which count by `banxico_status`): an in-flight row shows as `processing`/`queued` here but as `pending` in those buckets. All eight keys are always present (0 when absent) and always sum to `total`.
`queued` *	`integer`	Validations queued, not yet processed (async).
`processing` *	`integer`	Validations being processed against Banxico right now.
`valid` *	`integer`	Validations with lifecycle status `valid` (confirmed).
`not_found` *	`integer`	Validations with status `not_found`.
`cep_unavailable` *	`integer`	Validations with status `cep_unavailable`.
`invalid` *	`integer`	Validations with status `invalid` (invalid input).
`failed` *	`integer`	Validations with status `failed` (pipeline failure).
`error` *	`integer`	Validations with status `error`.

**Response status codes** `GET /v1/validations/stats`
Status	Class	Description	Body
200	`2xx`	Aggregated validation statistics for the user.	No body
401	`4xx`	Authentication is required or the provided credentials are invalid.	`ErrorResponse`

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