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

Look up account in own whitelist

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.

The lookup is isolated per account: a number absent from one's own list responds with HTTP status 404.

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`	Account number the lookup was made with, whether CLABE, card, or DiMo 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`	SPEI code (5 digits) of the resolved bank. It is the empty string (`""`) for a card whose BIN is not in the directory. e.g. `40012`
`bank_name`*	`string`	Official name of the bank, resolved from its `bank_code`. e.g. `BBVA MEXICO`
`label`	`string \| null`nullable	Free-form label, `null` when 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. `a1b2c3d4e5f66f5e4d3c2b1a`
`datetime`	`object`	Companion descriptor present in the `meta` block of every response (and in the `meta` of outgoing webhook bodies). 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 `d4e5f6a7b8c99c8b7a6f5e4d`
400	`query_param_account_required`	The `account` query parameter is required. Envelope meta.request_id `c3d4e5f6a7b88b7a6f5e4d3c`
401	`unauthorized`	Invalid or missing authentication credentials. Envelope meta.request_id `c4d5e6f7a8b99b8a7f6e5d4c`
403	`permission_denied`	You do not have permission to access this resource. Envelope meta.request_id `d5e6f7a8b9c00c9b8a7f6e5d`
404	`beneficiary_not_found_for_account`	No beneficiary found for this account. Envelope meta.request_id `b2c3d4e5f6a77a6f5e4d3c2b`