Schemas

SPEI participant bank in JSON:API shape. `id` and `attributes.code` are always equal (`id` is kept as the stable resource identifier even though `code` duplicates it).

A BIN resolution result from the local BIN catalog, in JSON:API shape. `id` and `attributes.bin` are equal: the 6-8 digit BIN that actually matched (never the full number the caller sent).

SPEI non-business-day calendar of one year, in JSON:API shape. `id` and `attributes.year` are always equal: the year of the calendar.

Response from `GET /v1/public/bin-lookup/{bin}`. A single resource with the issuing SPEI bank resolved against the local BIN catalog (pure read, no external lookup). An unknown BIN returns `404`, not this body.

Response from `GET /v1/public/banks`. Full SPEI participant catalog (~95 active institutions). ETag-cacheable — the snapshot updates weekly when the Banxico sync refreshes the catalog.

Response from `GET /v1/public/spei-calendar/{year}`. A single resource with the SPEI non-business days of the year and its source, and in `meta.covered_years` the years that have a calendar. A year without a calendar responds `404`, not this body.

Registered beneficiary account as a JSON:API resource. Can be a CLABE, a card number, or a DiMo phone number. The account type is auto-detected by length at insertion time.

Active-beneficiary allowance of the plan and current occupancy of the authenticated account.

Row extracted from a beneficiary import file, with its classification bucket and parsed fields. The account travels in full for the import owner, who reviews and corrects it before committing; the cross-user admin view masks it. Wrapped under `{ type, id, attributes }` following JSON:API format.

JSON:API resource carrying the resolved beneficiary account for the user.

Minimal JSON:API resource with the job ID and the new status after commit.

Multipart body for `POST /v1/beneficiaries/imports`: the file to import and the parse mode it is read with.

Minimal JSON:API resource with the job ID and its initial status.

Body for `POST /v1/beneficiaries`. Accepts two shapes: a flat object with attributes at the root, or the JSON:API envelope `{ data: { attributes: {...} } }`. The server tries `data.attributes` first and falls back to the root object. The account type (`clabe`, `card`, `phone`) is auto-detected by digit length: 18 = CLABE, 16 = card, 10 = phone (DiMo). When the detected type is `phone`, `bank_code` is **mandatory**; for CLABE and card the caller-supplied `bank_code` is ignored and derived from the CLABE prefix or BIN.

Body for `PATCH /v1/beneficiaries/imports/{id}/rows/{row_id}`. Accepts the JSON:API envelope `{ data: { attributes: {...} } }` or a flat object. All attributes are optional — only those present are overwritten. Five editable fields: `parsed_account`, `parsed_label`, `parsed_account_type`, `parsed_bank_code`, `parsed_bank_name`. Any other key is ignored. If no recognized editable field is present → `422 no_valid_fields`. If the job is not in `preview_ready` state → `422 job_not_editable`. After persisting the override, the server re-processes the row (re-derives bank from the new CLABE prefix / BIN) so that job counters and the preview's Bank column stay in sync without waiting for commit.

Body for `PUT /v1/beneficiaries/{id}`. Accepts JSON:API envelope `{ data: { attributes: {...} } }` or a flat object. All fields are optional — only those present are updated. If the body contains no editable field the server returns `422 no_valid_fields`. There are three update paths. With `label` alone, it is sanitized and stored. With a new `account_number`, `account_type`, `bank_code`, and `bank_name` are re-derived using the same rules as `POST /v1/beneficiaries`. With `bank_code` alone, the change only counts when the beneficiary is of type `phone`: On CLABE and card it is ignored silently — and it leaves the `beneficiary.phone_bank_updated` audit event when the code changes.

JSON:API resource carrying the structural validation result for the account.

Bulk beneficiary import job. Lifecycle: `pending` → `parsing` → `preview_ready` → `committing` → `completed` (or `failed` / `cancelled`). Wrapped under `{ type, id, attributes }` following JSON:API format.

A `202` response for `POST /v1/beneficiaries/imports/{id}/commit`: the import ID and its status once the commit has been queued (`committing`).

A `202` response for `POST /v1/beneficiaries/imports`: the ID of the newly created import and its initial status (`pending`).

Response for `POST /v1/beneficiaries`, with the beneficiary under `data`. Returns `201` when it creates a new record, and `200` when it reactivates an archived account with the same `account_number`: There `meta.reactivated` comes back `true`.

Response for `GET /v1/beneficiaries`: the authenticated user’s beneficiary accounts, as a flat array with no pagination. The `?with_archived` parameter decides which ones are included.

Response for `GET /v1/beneficiaries/lookup`: the beneficiary metadata when the queried account is among the authenticated user’s own.

Response for `PATCH /v1/beneficiaries/imports/{id}/rows/{row_id}`: the row once corrected and reprocessed. Its classification group (`status`) may have changed with the correction.

Response for `PUT /v1/beneficiaries/{id}`: the updated beneficiary, with the derived fields already recalculated.

Response from `GET /v1/beneficiaries/validate-account?account=`. Structural result for an account number. Under `data.attributes` it reports the detected type, the checksum, the resolved bank metadata (when possible) and, for 17-digit partial CLABEs, the auto-completed form. This endpoint does **not** call Banxico — purely local validation.

Response for `GET /v1/beneficiaries/imports/{id}`: the import with its current status and the per-group counters.

Response for `GET /v1/beneficiaries/imports/{id}/preview`: the parsed rows, paginated, with a snapshot of the import under `meta`. Accounts travel in full for the import owner; the cross-user admin view masks them.

Initial execution state of a confirmed import job.

Optional body of `POST /v1/validations/imports/{id}/commit`.

State of a newly created import job.

JSON import template delivered as a downloadable file.

Body of `PATCH /v1/validations/imports/{id}/rows/{row_id}`.

Validation retry policy: activation, limit, interval, and eligible outcomes.

Summary retry cycle state with configuration represented as `null`.

Full retry cycle state with configuration, progress, and current status.

Stable code for a validation failure. The list is not closed: an unexpected failure carries `internal_error` and other failures may carry the code of their cause, so treat an unknown value as a generic failure.

Input for a bulk import in `images` mode, with one or more PNG, JPG, or WEBP images.

JSON:API resource for a bulk validation import job and its execution state.

Interpreted row from an import job, from file reading through the validation outcome.

Input for a bulk import in `text` mode, with one CSV, XLSX, XLS, TXT, or JSON file.

Body of `POST /v1/validations/{id}/purge/execute`: the token from the preparation step.

Response of `POST /v1/validations/{id}/purge/execute`: the validation is now purged and this is what was deleted.

Response of `POST /v1/validations/{id}/purge/prepare`: what the permanent deletion would delete, what it would keep, and the token that confirms it. Nothing has changed yet.

Result of the follow-up check that comes with the response of `POST /v1/validations/{id}/recheck`, inside `meta`.

JSON:API resource with validation counters by `banxico_status`, lifecycle state, and validation mode.

Full retry cycle state after canceling a validation's pending retries.

Bulk import input whose `upload_type` selects text or images.

Body for `POST /v1/validate-ocr` with the receipt in `image` or `image_url`; requires at least one of the two fields. `cuenta_beneficiaria` and `cuentas_candidatas` cannot be sent together.

Summary JSON:API resource for a validation in the account history.

Automatic retry attempt for a validation.

Full retry cycle state after updating its retry policy.

Body of `PUT /v1/validations/{id}/retry-policy`.

JSON:API SPEI validation resource returned by the individual lookup and synchronous validation.

Body for `POST /v1/validate` for a manual SPEI validation; requires `clave_rastreo` or `referencia_numerica`, and exactly one of the two ways to give the account: `cuenta_beneficiaria` or `cuentas_candidatas`.

Body for `POST /v1/webhooks` with the receiving HTTPS URL, subscribed events, and an optional label.

Test-delivery result: receiver response, latency, or error.

Body for `PUT /v1/webhooks/{id}` with the endpoint fields to update.

JSON:API resource for a webhook delivery, with receiver, attempt, response, and status.

JSON:API resource for a webhook endpoint, with receiver URL, subscribed events, status, and secret representation.

Aggregate indicators for the account's validations.

Ranking of the account's banks by the requested metric.

Ranking of the account's beneficiaries by validations during the last 90 days.

Validation time series whose points contain volume or latency metrics according to `metric`.

JSON:API resource for a financial report preview.

Entry in the bank ranking by verified volume.

Financial report preview response with the CSV headers and up to 20 rows.

Account financial indicators for a calendar month, with aggregates, breakdowns, and comparison with the previous month.

JSON:API resource for the financial summary.

Response from `GET /v1/finance/summary` with the requested month's indicators in `data.attributes`.

API usage statistics, validation quota, and Banxico status for the account.

Account usage by operation type during the requested period.

Monthly usage history for the requested number of months.

Rate limits that apply to the account.

JSON:API resource carrying the validation heatmap.

Account validation quota for the current subscription cycle.

Response from `GET /v1/usage/heatmap` with validation density by weekday and hour.

JSON:API comparison resource with plans as columns and features as rows.

Bilingual plan feature with a visual indicator, order, and status.

Public plan-price attributes: currency, interval, kind, unit amount, and tax treatment.

Subscription plan attributes: usage limits, billing model, visibility, and order within the catalog.

Response from `GET /v1/plans/public/comparison` with the public plan matrix.

JSON:API resource for an active plan price.

Public-catalog plan with its active prices and features.

Response from `GET /v1/plans/{slug}/prices` with active prices and a plan summary in `meta.plan`.

One active plan from the authenticated catalog, with its active bilingual features.

Response from `GET /v1/plans/public` with the active plans in the public catalog, their prices, and features.

The user's active subscription, including its source, state, cycle, and limits. Each user has exactly one. The `trial_*`, `cancel_*`, and `stripe_subscription_id` fields are null when not applicable.

Quota summary for the active cycle. Returned at `meta.quota` by `GET /v1/billing/subscription`.

JSON:API resource containing the user's active subscription.

Active subscription and quota summary returned by `GET /v1/billing/subscription`.

Effective retry limits of the active plan, with global values when there is no override.

The account's saved retry policy: activation, limit, interval, and eligible outcomes. Disabled or not configured, it carries `enabled=false`, `max_retries=0`, `interval_seconds=0` and empty `outcomes`.

Consolidated set for the authenticated user returned by `GET /v1/users/me`: profile, API key metadata, active subscription, two-factor authentication (2FA) state, role permissions and notification summary in a single call.

A session of the account. It is created at sign-in, on passing the 2FA, or on a password change, and each one records where it was opened from and how long it is good for.

Request body to update the user's default retry policy (applies to future validations).

The authenticated user's active sessions, with their count. Revoked and expired ones are left out, and the list comes ordered by recency of use.

Public status of the Banxico validation service, as returned by `GET /v1/status/banxico`. It shows the current operational status and a human-readable explanation.

Time series of Banxico validation service health metrics, bucketed by time interval, as returned by `GET /v1/status/banxico/timeseries`.

JSON:API resource carrying the current public status snapshot.

JSON:API resource carrying the timeseries for the requested metric/window pair.

Response from `GET /v1/status/banxico`. Public reduced view of the Banxico validation service status, with no internal details. Cached 60s (via `Cache-Control` header in the response) — designed for health badges in customer dashboards.

Response from `GET /v1/status/banxico/timeseries`. Data points bucketed by time interval for the requested metric and window. Only exposes safe metrics (`probe_latency`, `verdict`); invalid query values silently fall back to defaults (`probe_latency`, `24h`).

JSON:API account dashboard summary with aggregate metrics, setup progress, and recent validations.

JSON:API request envelope for the Playground proxy. The server forwards the operation described in `data.attributes` to the target `/v1` endpoint using the caller's own API key (decrypted server-side), so the key never reaches the browser.

JSON:API envelope wrapping the categories and templates available for the playground, filtered by the calling user's permissions.

Companion descriptor present in the `meta` block of every response (and in the `meta` of outgoing webhook bodies). Lets clients assert the timezone contract without re-reading the spec.

A single error: the stable code the client branches on, the human-readable message — that one translated —, the HTTP status, and, when the failure is about one field, the pointer naming it.

Standard error response wrapper. The `code` field within each error is the stable, machine-readable contract — clients must branch on `code`, not `detail`.

Identity of a resource within the JSON:API envelope: the type it belongs to and its identifier. Every resource travelling in `data` carries it, alongside its `attributes`.

Current validation quota state: limit, usage, balance, and reset.

Standard successful response wrapper. The response payload is in `data`; request metadata is in `meta`; pagination or related links are in `links` when applicable.

ISO 8601 timestamp in UTC with an explicit `Z` suffix; for example, `"2026-05-01T05:14:38Z"`. The `*_at`, `*_end`, `*_start`, and `*_date` fields follow this format. `meta.datetime` describes the same contract in the response.

Asynchronous response from `POST /v1/validate?async=1` and `POST /v1/validate-ocr?async=1`. Contains the queued validation and the data needed to retrieve its result from `GET /v1/validations/{id}`.