Create a beneficiary

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

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

Registers a new beneficiary account. The account type (clabe, card, phone) is auto-detected from the account number length:

18 digits = CLABE — bank_code is derived from the prefix; any caller-supplied bank_code is ignored.
13–19 digits (except 18) = card — bank_code derived from the BIN via local directory with remote-lookup fallback.
10 digits = phone (DiMo) — bank_code is mandatory in the body.

If the account already exists active, returns 422 beneficiary_already_registered. If the account exists archived, it is reactivated and the endpoint returns 200 with meta.reactivated=true (not 201). Before creating you may validate the account structure with GET /v1/beneficiaries/validate-account (local CLABE/Luhn check, no Banxico round-trip). The bank_code for type phone is picked from the catalog at GET /v1/public/banks.

Parameters
Parameter	Type	Required	Description
`account_number`	string (pattern)	required	Account number. Accepted: 18-digit CLABE, 13–19 digit card (except 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 mxcep_••••' \
  -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
`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** `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`
401	`4xx`	Authentication is required or the provided credentials are invalid.	`ErrorResponse`
403	`4xx`	Permisos insuficientes	`ErrorResponse`
422	`4xx`	Validation failed. Possible codes: `account_number_required`, `invalid_account_format`, `invalid_clabe_checksum`, `invalid_card_luhn`, `clabe_prefix_not_recognized`, `bank_code_required_for_phone`, `invalid_bank_code`, `invalid_account_length`, `beneficiary_already_registered`.	`ErrorResponse`

**Errors from `POST /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`
422	`bank_code_required_for_phone`	A bank_code is required when registering a phone beneficiary. Envelope meta.request_id `f6a7b8c9d0e1`
422	`beneficiary_already_registered`	A beneficiary with this 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`