Update a beneficiary

PUT https://api.veriko.mx/v1/beneficiaries/{id}

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

Updates an existing beneficiary. Accepts JSON:API envelope or a flat object. Three paths:

label only: sanitized and persisted. - New account_number (the legacy clabe alias is also accepted): re-derives account_type, bank_code and bank_name using the same rules as POST /v1/beneficiaries. For type phone the body must include bank_code.
bank_code only: valid only when the existing beneficiary is of type phone; silently ignored for CLABE/card. Triggers the beneficiary.phone_bank_updated audit event when the code changes.

If the body has no editable field → 422 no_valid_fields.

Parameters
Parameter	In	Type	Required	Description
`id` *	path	`integer`	required	Numeric beneficiary ID.

Parameters
Parameter	Type	Required	Description
`label`	string (?–100)	optional	Optional free-form label. Sanitized with `strip_tags` + `trim`. e.g. `Proveedor XYZ`
`account_number`	string (pattern)	optional	New account number. Replaces the existing one and triggers the re-derivation of `account_type`, `bank_code` and `bank_name`. For type `phone`, `bank_code` must accompany the request. e.g. `012180004412345678`
`bank_code`	string (pattern)	optional	5-digit Banxico SPEI code. For `phone` beneficiaries, may be sent alone to reassign the DiMo receiving bank. For CLABE/card the field is ignored. e.g. `40021`

Request

cURLPython•JavaScript•PHP•

curl -X PUT 'https://api.veriko.mx/v1/beneficiaries/{id}' \
  -H 'Authorization: Bearer mxcep_••••' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "attributes": {
        "label": "Proveedor XYZ actualizado"
      }
    }
  }'

Python example — coming soon.

JavaScript example — coming soon.

PHP example — coming soon.

**Response 200** `UpdateBeneficiaryResponse` — Beneficiary updated.
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** `PUT /v1/beneficiaries/{id}`
Status	Class	Description	Body
200	`2xx`	Beneficiary updated.	`UpdateBeneficiaryResponse`
401	`4xx`	Authentication is required or the provided credentials are invalid.	`ErrorResponse`
403	`4xx`	Permisos insuficientes	`ErrorResponse`
404	`4xx`	The resource does not exist or is not visible to the caller	`Error`
422	`4xx`	Validation failed. Possible codes: `no_valid_fields`, `invalid_account_format`, `invalid_clabe_checksum`, `invalid_card_luhn`, `clabe_prefix_not_recognized`, `bank_code_required_for_phone`, `invalid_bank_code`, `invalid_account_length`.	`ErrorResponse`

**Errors from `PUT /v1/beneficiaries/{id}`**
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	`no_valid_fields`	No editable fields in request body. Envelope meta.request_id `d0e1f2a3b4c5`