Listar beneficiarios

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

Audiencia: public
Autenticación: API key
Permiso: beneficiaries:read

Devuelve las cuentas beneficiarias guardadas del usuario autenticado. La lista reúne los tres tipos de beneficiarios (CLABE, tarjeta y celular/DiMo).

El parámetro with_archived es opcional y controla la visibilidad de las cuentas archivadas. 0: solo activas; 1: solo archivadas.

Para resolver una cuenta concreta sin recorrer la lista, usa GET /v1/beneficiaries/lookup.

Para dar de alta varios beneficiarios a la vez (desde CSV o XLS), usa POST /v1/beneficiaries/imports.

Parámetros
Parámetro	Ubicación	Tipo	Obligatorio	Descripción
`with_archived`	query	`string`	opcional	Filtro tri-state: omitido = todas; `0` = solo activas; `1` = solo archivadas. p. ej. `0`

Petición

cURLPython•JavaScript•PHP•

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

Ejemplo en Python — próximamente.

Ejemplo en JavaScript — próximamente.

Ejemplo en PHP — próximamente.

**Respuesta 200**`ListBeneficiariesResponse` — Lista completa de cuentas beneficiarias del usuario según el filtro.
Campo	Tipo	Descripción
`data`	`array`	Payload principal de la respuesta. La forma varía según el endpoint (objeto, array, o envelope JSON:API con `type`, `id`, `attributes`).
`type`*	`string`	Tipo de recurso JSON:API. Siempre `beneficiary`. p. ej. `beneficiary`
`id`*	`string`	Identificador numérico del beneficiario en el sistema. p. ej. `42`
`attributes`*	`object`	Atributos canónicos del beneficiario (datos de la cuenta y metadatos del registro).
`account_number`*	`string`	Número de cuenta almacenado: CLABE (18 dígitos), tarjeta (16 dígitos) o celular/DiMo (10 dígitos). Use `account_type` para desambiguar el tipo exacto. p. ej. `012180004412345678`
`account_type`*	`string`	Tipo de cuenta: `clabe` (18 dígitos), `card` (16 dígitos) o `phone` (10 dígitos). p. ej. `clabe`
`bank_code`*	`string`	Código SPEI (5 dígitos) del banco resuelto. p. ej. `40012`
`bank_name`*	`string`	Nombre oficial del banco resuelto, derivado de su `bank_code`. p. ej. `BBVA MEXICO`
`label`	`string \| null`anulable	Etiqueta descriptiva libre del usuario. `null` si no fue asignada. p. ej. `Proveedor ABC`
`status`*	`string`	Estado del beneficiario. `inactive` si el beneficiario fue archivado o dado de baja. `active` si está en uso. p. ej. `active`
`created_at`*	`string (date-time)`	Marca temporal UTC de creación. p. ej. `2026-01-15T10:00:00Z`
`meta`	`object`	Metadatos de la respuesta, incluyendo versión de la API, prefijo de ruta, identificador único de la petición y marca temporal del servidor en UTC.
`version`	`string`	Versión de la API que procesó la petición. p. ej. `1.47.0`
`api_version`	`string`	Versión del prefijo de ruta de la API (ej. `v1`). p. ej. `v1`
`request_id`	`string`	Identificador único de la petición (hex). p. ej. `a1b2c3d4e5f6`
`datetime`	`object`	Descriptor compañero presente en el bloque `meta` de cada respuesta (y en el `meta` del cuerpo de los webhooks salientes). Permite a los clientes afirmar el contrato de zona horaria sin releer el spec. p. ej. `{"timezone":"UTC","format":"ISO 8601"}`
`timezone`*	`string`	Siempre `UTC` — la zona canónica para cada campo datetime del cuerpo. p. ej. `UTC`
`format`*	`string`	Siempre `ISO 8601` — sufijo `Z` explícito en cada datetime. p. ej. `ISO 8601`
`links`	`object`	Enlaces de paginación o relacionados, presentes solo cuando el endpoint devuelve una colección paginada.

**Códigos de respuesta**`GET /v1/beneficiaries`
Código	Clase	Descripción	Cuerpo
200	`2xx`	Lista completa de cuentas beneficiarias del usuario según el filtro.	`ListBeneficiariesResponse`
401	`4xx`	Se requiere autenticación o las credenciales son inválidas	`ErrorResponse`
403	`4xx`	Permisos insuficientes	`ErrorResponse`

**Errores de `GET /v1/beneficiaries`**
Código	Clave	Ejemplo
401	`unauthorized`	Credenciales de autenticación ausentes o inválidas. Envelope meta.request_id `c4d5e6f7a8b9`
403	`forbidden`	No tienes permiso para acceder a este recurso. Envelope meta.request_id `d5e6f7a8b9c0`