Schemas
Directory of JSON models used by the API. Every schema carries a bilingual description, property table and cross-references.
No matches.
Bank data
Banxico
-
BanxicoPublicStatusPublic Banxico CEP service status. Returned by `GET /v1/banxico/status` without authentication. Shows the current operational status and a human-readable explanation. -
BanxicoPublicStatusResponseResponse from `GET /v1/status/banxico`. Public reduced view of the Banxico CEP service status, with no internal details. Cached 60s (via `Cache-Control` header in the response) — designed for health badges in customer dashboards. -
BanxicoPublicTimeseriesTime-series of Banxico CEP service health metrics in time buckets. Returned by `GET /v1/banxico/timeseries`. -
BanxicoPublicTimeseriesResponseResponse 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`).
Beneficiaries
-
BeneficiaryRegistered 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. -
BeneficiaryImportJobBulk beneficiary import job. Lifecycle: `pending` → `parsing` → `preview_ready` → `committing` → `completed` (or `failed` / `cancelled`). Wrapped under `{ type, id, attributes }` following JSON:API format. -
BeneficiaryImportJobResponseResponse from `GET /v1/beneficiaries/imports/{id}`. Returns the full job with current status and per-bucket counters. Poll until `preview_ready` (to show the preview), `committed`/`completed` (to finalize the UI) or `failed`/`cancelled` (to end the flow). -
BeneficiaryImportPreviewResponseResponse from `GET /v1/beneficiaries/imports/{id}/preview`. Paginated parsed rows with a job snapshot in `meta`. CLABEs and phones are shown in full to the job owner; cards are also returned in full in the owner's view (the cross-user admin view masks them). -
BeneficiaryImportRowRow extracted from a beneficiary import file, with its classification bucket and parsed fields. Card numbers (PANs) are masked; CLABEs are shown in full to the job owner. Wrapped under `{ type, id, attributes }` following JSON:API format.
Envelopes & meta
Errors
Other
-
ApiUsageAPI usage statistics and Banxico service status. Returned by `GET /v1/api/usage`. -
BillingSubscriptionAttributesUser's active subscription resolved by `SubscriptionResolver::resolveActive`. Each user has exactly one active row; the origin is in `source`. The `trial_*`, `cancel_*` and `stripe_subscription_id` fields are null when not applicable (default free plans, admin grants, or steady-state subscriptions). All timestamps are UTC with `Z` suffix. -
BillingSubscriptionQuotaMetaQuota summary for the active cycle. Returned at `meta.quota` by `GET /v1/billing/subscription`. -
BillingSubscriptionResponseResponse of `GET /v1/billing/subscription`. The active subscription is exposed in `data`; the quota summary lives in `meta.quota` so legacy clients reading `effective_plan_slug` are unaffected. -
BinLookupResponseResponse from `GET /v1/public/bin-lookup/{bin}`. A single resource with the issuing SPEI bank resolved against the local `bin_directory` catalog (pure read, no external lookup). An unknown BIN returns `404`, not this body. -
BinResourceA BIN resolution result from the local `bin_directory` 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). -
CancelValidationRetriesAttributesResource attributes returned when cancelling a validation's pending retries (full retry state). -
CommitBeneficiaryImportResponseResponse from `POST /v1/beneficiaries/imports/{id}/commit` (HTTP 202). Minimal JSON:API envelope with the job ID and its new status (`committing`). The worker executes the commit; poll `GET /v1/beneficiaries/imports/{id}` until `completed` or `failed`. -
CommitValidationImportAttributes -
CommitValidationImportRequest -
CreateBeneficiaryImportRequestMultipart body for `POST /v1/beneficiaries/imports`. Uploads a file with beneficiaries and starts an asynchronous import job. A user may only have one active job at a time — an upload while another non-terminal job exists returns 422. -
CreateBeneficiaryImportResponseResponse from `POST /v1/beneficiaries/imports` (HTTP 202). Returns a minimal JSON:API envelope with the job ID and its initial status (`pending`). Poll `GET /v1/beneficiaries/imports/{id}` every 2s until the status is `preview_ready` or `failed`. -
CreateBeneficiaryRequestBody 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, 13–19 (≠18) = 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. -
CreateBeneficiaryResponseResponse from `POST /v1/beneficiaries`. When the endpoint creates a new record it returns `201` with the full beneficiary in `data`. When the endpoint reactivates an archived account (same `account_number` as a `status=inactive` record) it returns `200` with `meta.reactivated=true`. -
CreateValidationImportAttributes -
CreateValidationImportRequestDiscriminated request body to create a bulk validation import job (text input or images input). -
CreateWebhookRequestRequest body to create an outgoing webhook endpoint (HTTPS URL, list of subscribed events, and optional label). -
DashboardSummaryUser dashboard snapshot. Returned by `GET /summary`. `attributes` counts aggregate validations; `relationships.recent_validations` lists up to 10 recent validations (query param `?limit=N`, default 5). `comenzar_milestones_completed` measures progress through the `/comenzar` wizard and the post-login flow uses it to decide whether to skip that screen. -
DownloadValidationImportTemplateResponseResponse (empty body) when the endpoint serves the CSV template directly as binary content with `Content-Disposition`. -
FinancePreviewResponsePreview response for a financial report (`format=preview`). Returns the CSV headers and first 20 data rows so the UI can display a preview before the full download. -
FinanceSummaryAttributesUser financial KPIs for a calendar month. Includes counts by Banxico verdict, monetary aggregates, daily breakdown, top counterparties and banks, verdict distribution, and comparison with the previous month. -
FinanceSummaryResponseResponse from `GET /finance/summary?month=YYYY-MM`. Contains all financial KPIs for the month in a single block under `data.attributes`. -
FinanceTopBankBank in the verified volume ranking (sender or receiver). -
GetUsageBreakdownAttributesAttributes of the resource returned when querying the current period's usage breakdown by operation type (validations, OCR, etc.). -
GetUsageHeatmapResponseResponse of `GET /v1/usage/heatmap`. Validation density by (day-of-week, hour-of-day) combinations over the queried window. -
GetUsageHistoryAttributesAttributes of the resource returned when querying the user's monthly usage history (period, validations used, and applicable cap). -
GetUsageLimitsAttributesAttributes of the resource returned when querying the user's effective usage limits (per-IP and per-email rate limits + notes). -
InsightsOverviewAttributesValidation overview KPIs. Available in self (`self`) and platform-wide (`global`) scope. Returned by `GET /v1/insights/overview`. -
InsightsTopBanksAttributesBank ranking by selected metric. Returned by `GET /v1/insights/top-banks`. -
InsightsTopBeneficiariesAttributesUser's top beneficiaries by validation count (last 90 days). Returned by `GET /insights/top-beneficiaries`. When the user has a label in `/admin/beneficiaries` or `/beneficiaries`, `label` comes from there; otherwise it falls back to the OCR-captured receiver name. Only the last 4 digits of the account number are exposed — the rest is masked for privacy. -
InsightsTrendsAttributesTime-series validation data by metric and range. Returned by `GET /v1/insights/trends`. For `metric=volume`, each point contains `direct`, `ocr`, `valid`, and `errored`. For `metric=latency`, it contains percentiles `p50`, `p95`, `p99`, and `avg`. -
ListBanksResponseResponse 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. -
ListBeneficiariesResponseResponse from `GET /v1/beneficiaries`. Contains a flat array (no pagination) with all beneficiary accounts for the authenticated user. The tri-state `?with_archived` query parameter controls whether archived accounts are included. -
ListPlanPricesResponseResponse of `GET /v1/plans/{slug}/prices`. Lists the plan's active prices plus a mini summary of the plan in `meta.plan` to spare a round-trip to `/v1/plans/{slug}`. -
ListPlansItem -
ListPublicPlansResponseResponse of `GET /v1/plans/public`. Lists every active plan in the public catalog (visitor scope), including prices and features. -
LookupAccountDirectoryResponseResponse from `GET /v1/account-directory/lookup?last_digits=`. Most recent entry from the global account catalog whose suffix matches the given digits. **Does not include `account_number`** — only the bank and the last-seen timestamp, to prevent catalog enumeration. -
LookupBeneficiaryAccountResponseResponse from `GET /v1/beneficiaries/lookup?account=`. Returns the beneficiary metadata when the exact account number exists in the authenticated user's whitelist. -
OcrValidationRequestParameters for validating a SPEI transfer from a receipt image (OCR). At least one of `image` or `image_url` must be provided; if both are omitted the server returns 422. -
PatchBeneficiaryImportRowRequestBody 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. -
PatchBeneficiaryImportRowResponseResponse from `PATCH /v1/beneficiaries/imports/{id}/rows/{row_id}` with the row after applying the override and re-processing. The bucket (`status`) may have changed if the correction moved the row between `valid`, `correctable`, `fatal`, `duplicate_account` or `duplicate_alias`. -
PatchValidationImportRowRequest -
PlaygroundProxyRequestJSON: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. -
PlaygroundTemplatesResponseJSON:API envelope wrapping the categories and templates available for the playground, filtered by the calling user's permissions. -
SendWebhookTestAttributes -
UpdateBeneficiaryRequestBody 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`. Three update paths: - `label` only: sanitized and persisted. - New `account_number`: re-derives `account_type`, `bank_code` and `bank_name` using the same rules as `POST /v1/beneficiaries`. - `bank_code` only: valid only when the existing beneficiary is of type `phone`; silently ignored for CLABE/card. Triggers the `beneficiary.phone_bank_updated` audit event when the code changes. -
UpdateBeneficiaryResponseResponse from `PUT /v1/beneficiaries/{id}` with the updated beneficiary. -
UpdateUserRetryPolicyRequestRequest body to update the user's default retry policy (applies to future validations). -
UpdateValidationRetryPolicyAttributesResource attributes returned after updating a validation's retry policy (full retry state). -
UpdateValidationRetryPolicyRequestRequest body to update a validation's retry policy (backoff strategy and limits). -
UpdateWebhookRequest -
UsageSummarySnapshot of the user's validation consumption for the current month. Returned by `GET /usage/summary`. `tone` maps the percentage to a visual band (`ok`, `warn`, `danger`) the UI uses to color the meter. -
ValidateAccountResponseResponse 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.
Plans
-
PlanSubscription plan available on the platform. Returned by `GET /v1/plans` so the user can compare options and choose a plan. -
PlanComparisonResponsePublic plan comparison matrix (`GET /v1/plans/public/comparison`). Columns aligned to the public catalog; content is DB-editable. -
PlanFeatureBilingual plan feature bullet, displayed in the pricing card. Represents the `attributes` block within the JSON:API envelope; the `id` field lives at the envelope level. -
PlanPriceAttributesStripe price tied to a plan, surfaced to clients without revealing `stripe_price_id`. A plan may carry several prices for combinations of currency × interval × kind (`base` for the flat fee + optional `metered_overage` for metered overage).
Primitives
-
DatetimeMetaCompanion descriptor present in every response's meta block (and in outgoing webhook payloads). Lets clients assert the timezone contract without re-reading the spec. -
TimestampUTCISO 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.
Retry policy
-
RetryAttemptRecord of an individual automatic retry attempt. Returned in the `attempts` array from `GET /v1/validations/{id}/retry-attempts`. -
RetryPolicyAutomatic retry policy. Configures when and how many times the system retries a validation that returned an eligible outcome (`not_found`, `cep_unavailable` or `error` by default). -
RetryStateCompactCompact retry cycle state, included in list responses (`GET /v1/validations`). Contains the 4 most relevant fields for a list view; policy details (`max_retries`, `interval_seconds`, `outcomes`) are always `null` here and are only exposed in `RetryStateFull`. -
RetryStateFullFull retry cycle state, included in the individual validation response (`GET /v1/validations/{id}`). Exposes both state fields and the configured policy details.
Users
-
UserMeBundleConsolidated bundle for the authenticated user. Returned by GET /v1/users/me. Includes profile, API key metadata, active subscription, 2FA state, role permissions and notification summary in one roundtrip. -
UserSessionRepresents an active (or historical) JWT session of the authenticated user. A session is one cookie/JWT pair minted at login, 2FA verify, or the password-change re-issue; each one is anchored to a `jti` embedded in the JWT and recorded in `user_sessions` with its IP/UA and lifetime window. User-facing surface introduced in v1.49.5 (ADR-0089). -
UserSessionsList`attributes` block returned by `GET /v1/users/me/sessions`. Contains the authenticated user's active sessions and their count. Revoked or expired sessions are filtered server-side. Introduced in v1.49.5 (ADR-0089).
Validations
-
ValidationFull record of a SPEI validation as a JSON:API resource. Returned by `GET /v1/validations/{id}` and synchronous `POST /v1/validate`. -
ValidationImportImagesInputBulk import parameters for images mode. Upload one or more receipt images (PNG / JPG / WEBP) or a ZIP archive of images. Each image goes through the canonical OCR and normalization pipeline. -
ValidationImportJobJSON:API envelope for a bulk validation import job. State lifecycle: pending → parsing → preview_ready → committing → completed (or failed / cancelled). -
ValidationImportRowParsed row from a validation import batch. Represents the state of an individual validation within the batch, from parsing through the Banxico response. -
ValidationImportTextInputBulk import parameters for text mode. Upload a single CSV / XLSX / XLS / TXT / JSON file. The `parse_mode` field selects between canonical headers (`template`) or free-form line sweep (`free`). -
ValidationListItemAbbreviated validation for list views. Wrapped under `{ type, id, attributes }` following JSON:API format; the fields below describe the `attributes` block. Soft-deleted rows are also included — `is_deleted` and `deleted_at` allow the UI to distinguish them without an extra request. -
ValidationQueued202 response for the asynchronous validation flow (`POST /v1/validate?async=1` and `POST /v1/validate-ocr?async=1`). Indicates the validation was queued; poll `GET /v1/validations/{id}` for the final result. -
ValidationRequestParameters for validating a SPEI transfer against the Banxico CEP. At least one of `clave_rastreo` or `referencia_numerica` must be provided; if both are omitted the server returns 422. -
ValidationStatsAggregated counters for the authenticated user's validations. Returned by `GET /v1/validations/stats`. Honors the same filter set as `GET /v1/validations` (`date_from`, `date_to`, `type`, `search`, `with_deleted`, `playground`, `batch_id`).
Webhooks
-
WebhookDeliverySingle webhook delivery record (each retry increments `attempt`). Returned by `GET /webhooks/deliveries` (cross-endpoint feed) and `GET /webhooks/{id}/deliveries` (per-endpoint). The cross-endpoint variant adds a joined `endpoint_url` to avoid extra lookups. -
WebhookEndpointWebhook endpoint configured by the user. Delivery signatures use HMAC-SHA256 over the raw JSON body with `secret` as the key; the signature ships in `X-{Brand}-Signature: sha256=<hex>` alongside `X-{Brand}-Event`, `X-{Brand}-Delivery-Id` and `X-{Brand}-Timestamp`. The `X-{Brand}-Timestamp` value is ISO 8601 UTC (`format: date-time`, `Z` suffix), e.g. `2026-05-29T12:00:00Z`. The `secret` is returned in cleartext ONLY on create (`POST /webhooks`) and rotate (`POST /webhooks/{id}/regenerate-secret`); every other response substitutes `secret_hint` (last 4 characters).