Look up account in own whitelist

GET https://api.veriko.mx/v1/beneficiaries/lookup

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

Searches for the exact account number in the authenticated user's own beneficiary list. If found, returns bank metadata to auto-fill forms without manual lookup. Returns 404 when the account is not in the user's list. Never reveals whether the account exists in other users' lists. If you only need to validate the account number structure (CLABE checksum or card Luhn) without requiring registration, use GET /v1/beneficiaries/validate-account; for the global suffix-only fallback (does not expose the full number) see GET /v1/account-directory/lookup.

Parameters
Parameter	In	Type	Required	Description
`account` *	query	`string`	required	Full account number: 10 digits (phone), 13–19 (card) or 18 (CLABE). Separators are stripped before lookup.

Request

cURLPython•JavaScript•PHP•

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

Python example — coming soon.

JavaScript example — coming soon.

PHP example — coming soon.

**Response 200** `LookupBeneficiaryAccountResponse` — Account found in the user's list; returns bank metadata.
Field	Type	Description
`type` *	`string`	JSON:API resource type.
`attributes` *	`object`	Resolved account metadata.
`account_number` *	`string`	Queried account number (CLABE, card, or phone).
`account_type` *	`string`	Account type auto-detected at registration.
`bank_code` *	`string`	5-digit Banxico SPEI code of the receiving bank.
`bank_name` *	`string`	Resolved bank name.
`label`	`string \| null` nullable	Free-form label, `null` if none was assigned.

**Response status codes** `GET /v1/beneficiaries/lookup`
Status	Class	Description	Body
200	`2xx`	Account found in the user's list; returns bank metadata.	`LookupBeneficiaryAccountResponse`
400	`4xx`	`account` parameter missing (`query_param_account_required`) or invalid format (`invalid_account_format`).	`ErrorResponse`
401	`4xx`	Authentication is required or the provided credentials are invalid.	`ErrorResponse`
403	`4xx`	Permisos insuficientes	`ErrorResponse`
404	`4xx`	Account not found in the user's beneficiary list.	`ErrorResponse`

**Errors from `GET /v1/beneficiaries/lookup`**
Status	Code	Detail
400	`invalid_account_format`	The account format is not recognized. Envelope meta.request_id `d4e5f6a7b8c9`
400	`query_param_account_required`	The `account` query parameter is required. Envelope meta.request_id `c3d4e5f6a7b8`
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`
404	`beneficiary_not_found_for_account`	No beneficiary found for this account. Envelope meta.request_id `b2c3d4e5f6a7`