Look up account in own whitelist

GEThttps://api.veriko.mx/v1/beneficiaries/lookup

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

Looks up an exact account number within the beneficiary list of the authenticated account. When it exists, the response carries the bank details, which is what lets a form autocomplete without anyone typing them in.

The lookup is isolated per account: a number absent from one's own list responds 404, even if another account has it registered. The response never reveals the existence of someone else's account, and that is what separates it from the two neighbouring operations:

To check only the structure of the number — the CLABE check digit or the card's Luhn — without requiring it to be registered, there is GET /v1/beneficiaries/validate-account.
To resolve the bank of an account that is not one's own, the global directory answers by suffix and without exposing the full number: GET /v1/account-directory/lookup.

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

Request

cURLPython•JavaScript•PHP•

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

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
`data`	`object`	Main response payload. Shape varies by endpoint (object, array, or JSON:API envelope with `type`, `id`, `attributes`).
`type`*	`string`	JSON:API resource type. Always `beneficiary_lookup`. e.g. `beneficiary_lookup`
`attributes`*	`object`	Resolved account metadata.
`account_number`*	`string`	Queried account number (CLABE, card, or phone). e.g. `012180004412345678`
`account_type`*	`string`	Account type auto-detected at registration. `clabe` — 18-digit CLABE; `card` — 16-digit card; `phone` — 10-digit phone. e.g. `clabe`
`bank_code`*	`string`	5-digit Banxico SPEI code of the receiving bank. e.g. `40012`
`bank_name`*	`string`	Resolved bank name. e.g. `BBVA MEXICO`
`label`	`string \| null`nullable	Free-form label, `null` if none was assigned. e.g. `Proveedor ABC`
`meta`	`object`	Response metadata including API version, route prefix, unique request identifier, and the server timestamp in UTC.
`version`	`string`	API version that processed the request. e.g. `1.47.0`
`api_version`	`string`	API route prefix version (e.g. `v1`). e.g. `v1`
`request_id`	`string`	Unique request identifier (hex). e.g. `a1b2c3d4e5f6`
`datetime`	`object`	Companion descriptor present in every response's meta block (and in outgoing webhook payloads). Lets clients assert the timezone contract without re-reading the spec. e.g. `{"timezone":"UTC","format":"ISO 8601"}`
`timezone`*	`string`	Always `UTC` — the canonical timezone for every datetime field in the body. e.g. `UTC`
`format`*	`string`	Always `ISO 8601` — explicit `Z` suffix on every datetime. e.g. `ISO 8601`
`links`	`object`	Pagination or related links, present only when the endpoint returns a paginated collection.

**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`	Insufficient permissions.	`ErrorResponse`
404	`4xx`	Account not found in the user's beneficiary list.	`ErrorResponse`

**Errors from `GET /v1/beneficiaries/lookup`**
Status	Code	Example
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`