Validate account structure (CLABE, card, or phone)

GET https://api.veriko.mx/v1/beneficiaries/validate-account

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

Validates the structure of an account number without querying Banxico. Detects the type by length (18 = CLABE, 13–19 ≠18 = card, 10 = phone), verifies the control digit (CLABE) or Luhn (card) and resolves the bank. For partial 17-digit CLABEs the control digit is computed and appended automatically (auto_completed contains the resulting 18-digit CLABE). The endpoint always returns 200 when account is present: structural errors surface in checksum_valid=false or account_type='unknown' rather than as 422. Use this endpoint to validate form inputs before calling POST /v1/beneficiaries or POST /v1/validate, avoiding Banxico costs for accounts with invalid checksums.

Parameters
Parameter	In	Type	Required	Description
`account` *	query	`string`	required	Account digits (complete or partial). CLABE, card or phone. Minimum 1 digit, maximum 19.
`type`	query	`string`	optional	Forces the input interpretation instead of auto-detecting by length. `clabe` resolves the bank by prefix even for a partial CLABE (without mistaking it for a card); `bin` looks up a 6–8 digit BIN in the local directory (cache-only, no network). Omit for auto-detection.

Request

cURLPython•JavaScript•PHP•

curl -X GET 'https://api.veriko.mx/v1/beneficiaries/validate-account' \
  -H 'Authorization: Bearer mxcep_••••'

Python example — coming soon.

JavaScript example — coming soon.

PHP example — coming soon.

**Response 200** `ValidateAccountResponse` — Structural validation result. The body always has uniform shape; the `checksum_valid` and `account_type` flags communicate success or the reason for a structural rejection.
Field	Type	Description
`type` *	`string`	JSON:API resource type.
`attributes` *	`object`	Structural validation result.
`input` *	`string`	Raw input as received (un-normalized).
`length` *	`integer`	Length in digits of the normalized input.
`is_numeric` *	`boolean`	`true` when the raw input contained only digits (no separators).
`account_type` *	`string`	Account type detected by length, or `unknown` for partial inputs or out-of-range lengths.
`is_complete` *	`boolean`	`true` when the input is complete for its type (18 digits for CLABE, 13–19 for card, 10 for phone).
`checksum_valid` *	`boolean`	`true` when the CLABE control digit verifies, or the card Luhn checksum is valid. For phone always `false` (not applicable).
`computed_control_digit`	`string \| null` nullable	CLABE control digit computed from the first 17 digits. `null` when the type is not CLABE or the calculation does not apply.
`auto_completed`	`string \| null` nullable	18-digit auto-completed CLABE when the input arrived with 17 digits and the control digit could be calculated. `null` otherwise.
`bank`	`object \| null` nullable	Resolved bank metadata, or `null` when the bank could not be identified. For CLABE derived from the prefix; for card derived from the BIN.
`banxico_code`	`string \| null` nullable	5-digit Banxico SPEI code when the bank is mapped.
`name`	`string`	Bank name.
`card`	`object \| null` nullable	Additional BIN metadata when `account_type=card` and the BIN matched the directory. `null` otherwise.
`bin`	`string`	Queried BIN prefix.
`brand`	`string \| null` nullable	Card brand (Visa, Mastercard, etc.).
`type`	`string \| null` nullable	Card type (`debit`, `credit`, etc.).
`level`	`string \| null` nullable	Card level (`classic`, `gold`, etc.).
`country_iso`	`string \| null` nullable	ISO 3166-1 alpha-2 of the issuing country.

**Response status codes** `GET /v1/beneficiaries/validate-account`
Status	Class	Description	Body
200	`2xx`	Structural validation result. The body always has uniform shape; the `checksum_valid` and `account_type` flags communicate success or the reason for a structural rejection.	`ValidateAccountResponse`
400	`4xx`	`query_param_account_required` — the `account` parameter is empty.	`ErrorResponse`
401	`4xx`	Authentication is required or the provided credentials are invalid.	`ErrorResponse`
403	`4xx`	Permisos insuficientes	`ErrorResponse`

**Errors from `GET /v1/beneficiaries/validate-account`**
Status	Code	Detail
400	`query_param_account_required`	The `account` query parameter is required. Envelope meta.request_id `f6a7b8c9d0e1`
401	`unauthorized`	Invalid or missing authentication credentials. Envelope meta.request_id `c4d5e6f7a8b9`
403	`forbidden`	You do not have permission to access this resource. Envelope meta.request_id `d5e6f7a8b9c0`