Schemas
Directory of JSON models used by the API. Every schema carries a bilingual description, property table and cross-references.
No matches.
Public4
BankResourceSPEI 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). usesJsonApiResourceBaseused by 1BinLookupResponseResponse 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. usesBinResource,SuccessEnvelopeBinResourceA 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). usesJsonApiResourceBaseused by 1ListBanksResponseResponse 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. usesBankResource,SuccessEnvelope
Beneficiaries21
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. usesJsonApiResourceBaseused by 3BeneficiaryImportJobBulk beneficiary import job. Lifecycle: `pending` → `parsing` → `preview_ready` → `committing` → `completed` (or `failed` / `cancelled`). Wrapped under `{ type, id, attributes }` following JSON:API format. usesJsonApiResourceBase,TimestampUTCused by 2BeneficiaryImportJobResponseResponse 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). usesBeneficiaryImportJob,SuccessEnvelopeBeneficiaryImportPreviewResponseResponse 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). usesBeneficiaryImportJob,BeneficiaryImportRow,SuccessEnvelopeBeneficiaryImportRowRow 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. usesJsonApiResourceBaseused by 2BeneficiaryLookupResourceJSON:API resource carrying the resolved beneficiary account for the user.used by 1CommitBeneficiaryImportResourceMinimal JSON:API resource with the job ID and the new status after commit.usesJsonApiResourceBaseused by 1CommitBeneficiaryImportResponseResponse 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`. usesCommitBeneficiaryImportResource,SuccessEnvelopeCreateBeneficiaryImportRequestMultipart 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.CreateBeneficiaryImportResourceMinimal JSON:API resource with the job ID and its initial status.usesJsonApiResourceBaseused by 1CreateBeneficiaryImportResponseResponse 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`. usesCreateBeneficiaryImportResource,SuccessEnvelopeCreateBeneficiaryRequestBody 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.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`. usesBeneficiary,SuccessEnvelopeListBeneficiariesResponseResponse 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. usesBeneficiary,SuccessEnvelopeLookupBeneficiaryAccountResponseResponse from `GET /v1/beneficiaries/lookup?account=`. Returns the beneficiary metadata when the exact account number exists in the authenticated user's whitelist. usesBeneficiaryLookupResource,SuccessEnvelopePatchBeneficiaryImportRowRequestBody 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`. usesBeneficiaryImportRow,SuccessEnvelopeUpdateBeneficiaryRequestBody 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.UpdateBeneficiaryResponseResponse from `PUT /v1/beneficiaries/{id}` with the updated beneficiary.usesBeneficiary,SuccessEnvelopeValidateAccountResourceJSON:API resource carrying the structural validation result for the account.used by 1ValidateAccountResponseResponse 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. usesSuccessEnvelope,ValidateAccountResource
Validations23
CancelValidationRetriesAttributesResource attributes returned when cancelling a validation's pending retries (full retry state).usesRetryStateFullCommitValidationImportAttributesResult of confirming the batch: how many rows it carried and how many were queued for processing.CommitValidationImportRequestBody used to confirm an already reviewed validation batch and send it to be processed.CreateValidationImportAttributesInitial state of the freshly created batch, before its rows are reviewed.CreateValidationImportRequestDiscriminated request body to create a bulk validation import job (text input or images input).usesValidationImportImagesInput,ValidationImportTextInputDownloadValidationImportTemplateResponseResponse (empty body) when the endpoint serves the CSV template directly as binary content with `Content-Disposition`.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. usesRetryPolicyPatchValidationImportRowRequestBody used to fix one row of the batch before confirming it.RetryAttemptRecord of an individual automatic retry attempt. Returned in the `attempts` array from `GET /v1/validations/{id}/retry-attempts`. usesTimestampUTC,ValidationErrorCodeRetryPolicyAutomatic 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). used by 4RetryStateCompactCompact 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`. usesTimestampUTCused by 1RetryStateFullFull retry cycle state, included in the individual validation response (`GET /v1/validations/{id}`). Exposes both state fields and the configured policy details. usesTimestampUTCused by 4UpdateValidationRetryPolicyAttributesResource attributes returned after updating a validation's retry policy (full retry state).usesRetryStateFullUpdateValidationRetryPolicyRequestRequest body to update a validation's retry policy (backoff strategy and limits).usesRetryPolicyValidationFull record of a SPEI validation as a JSON:API resource. Returned by `GET /v1/validations/{id}` and synchronous `POST /v1/validate`. usesJsonApiResourceBase,RetryStateFull,ValidationErrorCodeValidationErrorCodeError code for a validation in terminal state `error` or `failed`. The codes `network`, `captcha`, and `max_retries_exceeded` trigger the `validation.error` webhook event; the rest are only accessible via GET. used by 2ValidationImportImagesInputBulk 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. used by 1ValidationImportJobJSON:API envelope for a bulk validation import job. State lifecycle: pending → parsing → preview_ready → committing → completed (or failed / cancelled). usesJsonApiResourceBase,TimestampUTCValidationImportRowParsed row from a validation import batch. Represents the state of an individual validation within the batch, from parsing through the Banxico response. usesJsonApiResourceBaseValidationImportTextInputBulk 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`). used by 1ValidationListItemAbbreviated 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. usesRetryStateCompact,TimestampUTCValidationRequestParameters 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. usesRetryPolicyValidationStatsAggregated 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`).
Account Directory2
AccountDirectoryLookupResourceJSON:API resource with the directory entry matching the queried suffix.used by 1LookupAccountDirectoryResponseResponse 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. usesAccountDirectoryLookupResource,SuccessEnvelope
Webhooks5
CreateWebhookRequestRequest body to create an outgoing webhook endpoint (HTTPS URL, list of subscribed events, and optional label).SendWebhookTestAttributesResult of the test delivery to the receiver: whether it answered, with what status and how fast — or the error it gave.UpdateWebhookRequestBody used to change a webhook receiver: its address, the events it listens to, and whether it stays active.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. usesJsonApiResourceBase,TimestampUTCWebhookEndpointWebhook 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). usesJsonApiResourceBase,TimestampUTC
Insights4
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`.
Finance6
FinancePreviewResourceJSON:API wrapper for the preview.used by 1FinancePreviewResponsePreview 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. usesFinancePreviewResource,SuccessEnvelopeFinanceSummaryAttributesUser 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. usesFinanceTopBankused by 1FinanceSummaryResourceJSON:API wrapper for the financial summary.usesFinanceSummaryAttributesused by 1FinanceSummaryResponseResponse from `GET /finance/summary?month=YYYY-MM`. Contains all financial KPIs for the month in a single block under `data.attributes`. usesFinanceSummaryResource,SuccessEnvelopeFinanceTopBankBank in the verified volume ranking (sender or receiver).used by 1
Usage7
ApiUsageAPI usage statistics and Banxico service status. Returned by `GET /v1/api/usage`. usesPlanQuotaState,TimestampUTCGetUsageBreakdownAttributesAttributes 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. usesSuccessEnvelope,UsageHeatmapResourceGetUsageHistoryAttributesAttributes 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).UsageHeatmapResourceJSON:API resource carrying the heatmap.used by 1UsageSummarySnapshot 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. usesTimestampUTC
Plans10
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}`. usesPlanPriceResource,SuccessEnvelopeListPlansItemOne plan from the public catalogue, with its price and the bullets that describe it in both languages.usesJsonApiResourceBase,PlanListPublicPlansResponseResponse of `GET /v1/plans/public`. Lists every active plan in the public catalog (visitor scope), including prices and features. usesPublicPlanResource,SuccessEnvelopePlanSubscription plan available on the platform. Returned by `GET /v1/plans` so the user can compare options and choose a plan. usesPlanFeatureused by 1PlanComparisonResourceThe plan comparison row by row: each feature and what every plan offers on it.used by 1PlanComparisonResponsePublic plan comparison matrix (`GET /v1/plans/public/comparison`). Columns aligned to the public catalog; content is DB-editable. usesPlanComparisonResource,SuccessEnvelopePlanFeatureBilingual 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. used by 2PlanPriceAttributesStripe 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). used by 2PlanPriceResourceOne plan price, with its currency, its cadence, and the Stripe price it maps to.usesJsonApiResourceBase,PlanPriceAttributesused by 1PublicPlanResourceA plan as published: what it includes and what it costs, with none of the internal administration.usesJsonApiResourceBase,PlanFeature,PlanPriceAttributesused by 1
Billing4
BillingSubscriptionAttributesUser's active subscription. 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. usesTimestampUTCused by 1BillingSubscriptionQuotaMetaQuota summary for the active cycle. Returned at `meta.quota` by `GET /v1/billing/subscription`. usesTimestampUTCused by 1BillingSubscriptionResourceJSON:API resource carrying the user's active billing subscription.usesBillingSubscriptionAttributes,JsonApiResourceBaseused by 1BillingSubscriptionResponseResponse 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. usesBillingSubscriptionQuotaMeta,BillingSubscriptionResource,SuccessEnvelope
Users4
UpdateUserRetryPolicyRequestRequest body to update the user's default retry policy (applies to future validations).usesRetryPolicyUserMeBundleConsolidated 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.UserSessionAn open —or already closed— session of the account. It is created at sign-in, on passing the second factor, or on a password change, and each one records where it was opened from and how long it is good for. used by 1UserSessionsList`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. Sessions come sorted by recency of use. usesUserSession
Banxico Status6
BanxicoPublicStatusPublic Banxico CEP service status. Returned by `GET /v1/banxico/status` without authentication. Shows the current operational status and a human-readable explanation. usesTimestampUTCused by 1BanxicoPublicStatusResourceJSON:API resource carrying the current public status snapshot.usesBanxicoPublicStatus,JsonApiResourceBaseused by 1BanxicoPublicStatusResponseResponse 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. usesBanxicoPublicStatusResource,SuccessEnvelopeBanxicoPublicTimeseriesTime-series of Banxico CEP service health metrics in time buckets. Returned by `GET /v1/banxico/timeseries`. usesTimestampUTCused by 1BanxicoPublicTimeseriesResourceJSON:API resource carrying the timeseries for the requested metric/window pair.usesBanxicoPublicTimeseries,JsonApiResourceBaseused by 1BanxicoPublicTimeseriesResponseResponse 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`). usesBanxicoPublicTimeseriesResource,SuccessEnvelope
Dashboard1
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. usesJsonApiResourceBase,TimestampUTC
Playground2
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.
Common8
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. used by 2ErrorObjectA 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.used by 1ErrorResponseStandard error response wrapper. The `code` field within each error is the stable, machine-readable contract — clients must branch on `code`, not `detail`. usesDatetimeMeta,ErrorObjectJsonApiResourceBaseIdentity 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`. used by 20PlanQuotaStateValidation quota state for the plan in force: how many it includes, how many have been used, how many remain, and when the count resets.usesTimestampUTCused by 1SuccessEnvelopeStandard successful response wrapper. The response payload is in `data`; request metadata is in `meta`; pagination or related links are in `links` when applicable. usesDatetimeMetaused by 22TimestampUTCISO 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. used by 17ValidationQueued202 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. usesJsonApiResourceBase,RetryStateFull,TimestampUTC