List beneficiaries

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

List beneficiaries

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

Returns the saved beneficiary accounts for the authenticated user, without pagination. Includes CLABE, card, and phone (DiMo) accounts. The with_archived parameter controls archived account visibility (tri-state):

omitted or empty: includes active and archived (default behavior);
0: active only; - 1: archived only. To resolve a specific account without paginating the list use GET /v1/beneficiaries/lookup; to load many beneficiaries at once from CSV/XLS use POST /v1/beneficiaries/imports.

Parameters
Parameter	In	Type	Required	Description
`with_archived`	query	`string`	optional	Tri-state filter: omitted = all; `0` = active only; `1` = archived only.

Request

cURLPython•JavaScript•PHP•

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

Python example — coming soon.

JavaScript example — coming soon.

PHP example — coming soon.

**Response 200** `ListBeneficiariesResponse` — Complete list of the user's beneficiary accounts per the filter.
Field	Type	Description
`type` *	`string`	JSON:API resource type. Always `beneficiary`.
`id` *	`integer`	Auto-increment numeric identifier of the beneficiary in the `user_beneficiaries` table.
`attributes` *	`object`	Canonical beneficiary attributes (recipient account data and record metadata).
`account_number` *	`string`	Stored account number: 18-digit CLABE, 13-19 digit card, or 10-digit DiMo phone. Use `account_type` to disambiguate the exact type.
`account_type` *	`string`	Auto-detected account type: `clabe` (18 digits), `card` (13-19 digits), or `phone` (10 digits, DiMo mobile).
`bank_code` *	`string`	5-digit Banxico code of the receiving bank, derived from the CLABE prefix, card BIN, or DiMo catalog.
`bank_name` *	`string`	Bank name resolved from the CLABE prefix, card BIN, or DiMo catalog.
`label`	`string \| null` nullable	User-assigned descriptive label. `null` if not provided.
`status` *	`string`	Beneficiary status. `inactive` is set when the beneficiary is archived (excluded from default listings).
`created_at` *	`string (date-time)`	UTC creation timestamp.

**Response status codes** `GET /v1/beneficiaries`
Status	Class	Description	Body
200	`2xx`	Complete list of the user's beneficiary accounts per the filter.	`ListBeneficiariesResponse`
401	`4xx`	Authentication is required or the provided credentials are invalid.	`ErrorResponse`
403	`4xx`	Permisos insuficientes	`ErrorResponse`

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