Create a beneficiary

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

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

Registers a new beneficiary account. The account type is auto-detected from the number's length, and which fields are required follows from it:

18 digits, CLABE: bank_code is derived from the prefix, and any value sent in the body is ignored.
16 digits, card: bank_code is derived from the BIN.
10 digits, phone (DiMo): bank_code is mandatory in the body, because the number alone does not identify the institution.

An account that already exists active is not duplicated: the response is 422 beneficiary_already_registered. If it exists but is archived, the request reactivates it and responds 200 with meta.reactivated=true, not 201. An integration that only inspects the 2xx range cannot tell the two cases apart; meta.reactivated is what separates them.

The account structure can be checked beforehand with GET /v1/beneficiaries/validate-account, which resolves the format without querying Banxico. The bank_code for a phone account comes from the catalogue at GET /v1/public/banks.

Parameters
Parameter	Type	Required	Description
`account_number`	string (pattern)	required	Account number. Accepted: 18-digit CLABE, 16-digit card (only 18, reserved for CLABE) or 10-digit DiMo phone. Separators (spaces, hyphens) are stripped before validation. e.g. `012180004412345678`
`bank_code`	string (pattern)	optional	5-digit Banxico SPEI code. Required when the detected type is `phone`; ignored for CLABE and card (derived from prefix or BIN). When applicable the code is validated against the current SPEI participant catalog. e.g. `40012`
`label`	string (?–100)	optional	Optional free-form label. Sanitized with `strip_tags` + `trim` before persistence. e.g. `Proveedor ABC`

Request

cURLPython•JavaScript•PHP•

curl -X POST 'https://api.veriko.mx/v1/beneficiaries' \
  -H 'Authorization: Bearer veriko_••••' \
  -H 'Content-Type: application/json' \
  -d '{
    "account_number": "4111111111111111",
    "label": "Tarjeta BBVA nómina"
  }'

Python example — coming soon.

JavaScript example — coming soon.

PHP example — coming soon.

**Response 2xx**`CreateBeneficiaryResponse`
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`. e.g. `beneficiary`
`id`*	`string`	Auto-increment numeric identifier of the beneficiary in the `user_beneficiaries` table. e.g. `42`
`attributes`*	`object`	Canonical beneficiary attributes (recipient account data and record metadata).
`account_number`*	`string`	Stored account number: 18-digit CLABE, 16-digit card, or 10-digit DiMo phone. Use `account_type` to disambiguate the exact type. e.g. `012180004412345678`
`account_type`*	`string`	Auto-detected account type: `clabe` (18 digits), `card` (16 digits), or `phone` (10 digits, DiMo mobile). e.g. `clabe`
`bank_code`*	`string`	5-digit Banxico code of the receiving bank, derived from the CLABE prefix, card BIN, or DiMo catalog. e.g. `40012`
`bank_name`*	`string`	Bank name resolved from the CLABE prefix, card BIN, or DiMo catalog. e.g. `BBVA MEXICO`
`label`	`string \| null`nullable	User-assigned descriptive label. `null` if not provided. e.g. `Proveedor ABC`
`status`*	`string`	Beneficiary status. `inactive` is set when the beneficiary is archived (excluded from default listings). `active` — in use; `inactive` — retired without being deleted. e.g. `active`
`created_at`*	`string (date-time)`	UTC creation timestamp. e.g. `2026-01-15T10:00:00Z`
`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**`POST /v1/beneficiaries`
Status	Class	Description	Body
200	`2xx`	Beneficiary reactivated (an archived record existed for the same `account_number`). Includes `meta.reactivated=true`.	`CreateBeneficiaryResponse`
201	`2xx`	Beneficiary created.	`CreateBeneficiaryResponse`
400	`4xx`	The request body is empty or is not valid JSON.	`ErrorResponse`
401	`4xx`	Authentication is required or the provided credentials are invalid.	`ErrorResponse`
403	`4xx`	Insufficient permissions.	`ErrorResponse`
413	`4xx`	The request body exceeds the maximum accepted size (`body_too_large`).	`ErrorResponse`
422	`4xx`	The account failed validation, or the request hit a cap. Possible codes are `account_number_required`, `invalid_account_length`, `clabe_prefix_not_recognized`, `bank_code_required_for_phone`, `beneficiary_already_registered`, and `plan_cap_exceeded` — the last one when the account's plan sets a maximum number of beneficiaries and the request would exceed it.	`ErrorResponse`

**Errors from `POST /v1/beneficiaries`**
Status	Code	Example
400	`body_empty`	The request body is empty. Envelope meta.request_id `c1d2e3f4a5b6`
400	`invalid_json`	The body is not valid JSON. Envelope meta.request_id `d2e3f4a5b6c7`
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`
413	`body_too_large`	The request body is too large. Envelope meta.request_id `1a2b3c4d5e6f`
422	`bank_code_required_for_phone`	A `bank_code` is required to register a phone-type beneficiary. Envelope meta.request_id `f6a7b8c9d0e1`
422	`beneficiary_already_registered`	A beneficiary with that account number already exists. Envelope meta.request_id `b8c9d0e1f2a3`
422	`clabe_prefix_not_recognized`	The CLABE prefix does not match any SPEI participant. Envelope meta.request_id `a7b8c9d0e1f2`
422	`plan_cap_exceeded`	The account's plan does not allow more beneficiaries. Envelope meta.request_id `f4a5b6c7d8e9`