Docs
ES
GEThttps://api.veriko.mx/v1/validations/stats

Validation statistics for the user

Audience
public
Auth
API key
Permission
validations:read
How-to guide →

Returns the account's validations counted in two different ways, and the distinction matters:

  • The top-level counters — valid, not_found, cep_unavailable, error, pending — count by verdict, which is what Banxico answered. other is the remainder, in practice the invalid rows.
  • by_status counts by lifecycle state (queued, processing, valid, …), the same axis the list filters on. Its buckets sum to the total.

by_type splits between direct and OCR validation, and deleted counts the ones withdrawn from the history.

The filters are the same as on GET /v1/validations — dates, type, search, bank, amount, playground, batch, and deleted — with one exception: status is accepted and does not change the numbers, because each counter carries its own criterion.

Parameters
ParameterInTypeRequiredDescription
amount_maxquerynumber (float)optional

Inclusive maximum amount (normalized_data, fallback request_data).

e.g. 50000
amount_minquerynumber (float)optional

Inclusive minimum amount (normalized_data, fallback request_data).

e.g. 1000.5
bankquerystringoptional

Restricts the counters to the bank's 3-digit SPEI code (receiver or sender). Digits only, max 5 characters.

e.g. 012
batch_idqueryintegeroptional

Restricts the counters to the batch of a bulk import.

e.g. 42
fromquerystring (date)optional

Inclusive start date (YYYY-MM-DD).

e.g. 2025-01-01
playgroundquerystringoptional

Keeps only validations made from the playground. The only accepted value is 1: anything else — true included — answers 422 rather than being ignored, so it is clear the filter was not applied.

e.g. 1
retry_statequerystringoptional

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.

e.g. pending
searchquerystringoptional

Search by tracking key, numeric reference, sender, and receiver.

e.g. MXBA
statusquerystringoptional

Accepted, and it does not change the numbers. It exists so a UI can forward the same filter set it uses on GET /v1/validations without stripping it; every figure in this response carries its own criterion and is not narrowed by status. The other filters — dates, bank, amount, type — do apply.

e.g. valid
toquerystring (date)optional

Inclusive end date (YYYY-MM-DD).

e.g. 2025-03-31
typequerystringoptional

How the validation was requested: direct with the fields typed in, ocr from an image of the receipt.

e.g. direct
with_deletedquerystringoptional

Whether to include deleted validations. 0 keeps only the live ones — the default — and 1 includes the deleted ones too. Deleted validations keep their result: they are what makes an already-exported history reconcile.

e.g. 0
Request
curl -X GET 'https://api.veriko.mx/v1/validations/stats' \
  -H 'Authorization: Bearer veriko_••••'

Python example — coming soon.

JavaScript example — coming soon.

PHP example — coming soon.

Try it in the playground →
Response 200ValidationStats — Aggregated validation statistics for the user.
FieldTypeDescription
typestring

JSON:API resource type (always validation_stats).

e.g. validation_stats
attributesobject

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).

totalinteger

Total count of the user's validations matching the filters. Counts every row regardless of Banxico status.

e.g. 47
validinteger

Subset of the total with banxico_status='valid' (transfer confirmed).

e.g. 35
not_foundinteger

Subset of the total with banxico_status='not_found'.

e.g. 5
cep_unavailableinteger

Subset of the total with banxico_status='cep_unavailable' (the Banxico CEP service was unavailable at validation time).

e.g. 2
errorinteger

Subset of the total with banxico_status='error' (Banxico error, e.g. HTTP 5xx or network failure).

e.g. 1
pendinginteger

Subset of the total with banxico_status='pending': async validations still queued or processing, with no CEP result yet.

e.g. 1
deletedinteger

Count of the user's soft-deleted validations (matching the same filters).

e.g. 2
otherinteger

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).

e.g. 1
by_typeobject

Breakdown by validation type. direct + ocr always sums to total.

direct*integer

Direct validations (by CLABE/card/phone fields).

e.g. 30
ocr*integer

OCR validations (from a receipt image).

e.g. 17
by_statusobject

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).

e.g. 3
processing*integer

Validations being processed against Banxico right now.

e.g. 1
valid*integer

Validations with lifecycle status valid (confirmed).

e.g. 35
not_found*integer

Validations with status not_found.

e.g. 5
cep_unavailable*integer

Validations with status cep_unavailable.

e.g. 2
invalid*integer

Validations with status invalid (invalid input).

e.g. 1
failed*integer

Validations with status failed (pipeline failure).

e.g. 0
error*integer

Validations with status error.

e.g. 1
Response status codesGET /v1/validations/stats
StatusClassDescriptionBody
2002xxAggregated validation statistics for the user.No body
4014xxAuthentication is required or the provided credentials are invalid.ErrorResponse
4224xxA filter carries a value outside its allowed list. The code is invalid_filter and the detail names the parameter.ErrorResponse
Errors from GET /v1/validations/stats
StatusCodeExample
401unauthorized

Invalid or missing authentication credentials.

Envelope
meta.request_id
c4d5e6f7a8b9
422invalid_filter

The `retry_state` filter has an unsupported value.

Envelope
meta.request_id
c3d4e5f6a1b2