PUThttps://api.veriko.mx/v1/beneficiaries/{id}

Update a beneficiary

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

Updates an already registered beneficiary. The body accepts the JSON:API envelope or a flat object, and what is sent determines the scope of the change:

label only: it is stored, leaving the account untouched.
A new account_number: account_type, bank_code and bank_name are derived again. If the new number is a phone, the body must carry bank_code.
bank_code only: it applies solely to a phone-type beneficiary. On a CLABE or a card the bank is derived from the number, so the value sent is discarded without an error; if it was the only field, the response is no_valid_fields.

A body with no editable field responds with HTTP status 422, with no_valid_fields in the body.

If the new account_number is already registered under the same user account, active or archived, it responds with HTTP status 422, with beneficiary_already_registered in the body, and the beneficiary does not change.

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

Parameters
Parameter	Type	Required	Description
`label`	string (?–100)	optional	Optional label the account is identified by in the beneficiary list. 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	SPEI code (4 or 5 digits) of the beneficiary's bank. For CLABE/card the field is ignored. For phone/DiMo it may be sent alone to reassign the receiving bank. e.g. `40021`

Request

cURLPython•JavaScript•PHP•

curl -X PUT 'https://api.veriko.mx/v1/beneficiaries/{id}' \
  -H 'Authorization: Bearer veriko_••••' \
  -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
`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`	Numeric identifier of the beneficiary in the system. 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`	SPEI code (5 digits) of the resolved bank. It is the empty string (`""`) when the account has no known bank: a card whose BIN is not in the directory. In that case `bank_name` carries a placeholder text in the language of the request. e.g. `40012`
`bank_name`*	`string`	Official name of the bank, resolved from its `bank_code`. With an empty `bank_code` it is a placeholder text ("Unrecognized BIN (411111)"), translated into the language of the request. e.g. `BBVA MEXICO`
`label`	`string \| null`nullable	User-assigned descriptive label. `null` when not provided. e.g. `Proveedor ABC`
`status`*	`string`	Beneficiary status. `inactive` if the beneficiary was archived. `active` if it is in use. e.g. `active`
`created_at`*	`string (date-time)`	Date and time, in ISO 8601 UTC, of creation. 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. `a1b2c3d4e5f66f5e4d3c2b1a`
`datetime`	`object`	Companion descriptor present in the `meta` block of every response (and in the `meta` of outgoing webhook bodies). 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**`PUT /v1/beneficiaries/{id}`
Status	Class	Description	Body
200	`2xx`	Beneficiary updated.	`UpdateBeneficiaryResponse`
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`
404	`4xx`	The resource does not exist or is not visible to the client	`Error`
413	`4xx`	The request body exceeds the maximum accepted size (`body_too_large`).	`ErrorResponse`
422	`4xx`	The body failed validation. Possible codes are `no_valid_fields`, `invalid_account_format`, `invalid_account_length`, `invalid_clabe_checksum`, `invalid_card_luhn`, `clabe_prefix_not_recognized`, `bank_code_required_for_phone`, `invalid_bank_code`, `max_length_exceeded`, `beneficiary_already_registered`, `account_number_invalid_type`, and `label_invalid_type`. The last two fire when `account_number` or `label` arrive as a type other than a string (a number or an array, for instance). Every field-level error carries `source.pointer`.	`ErrorResponse`

**Errors from `PUT /v1/beneficiaries/{id}`**
Status	Code	Example
400	`body_empty`	The request body is empty. Envelope meta.request_id `a5b6c7d8e9f00f9e8d7c6b5a`
400	`invalid_json`	The body is not valid JSON. Envelope meta.request_id `b6c7d8e9f0a11a0f9e8d7c6b`
401	`unauthorized`	Invalid or missing authentication credentials. Envelope meta.request_id `c4d5e6f7a8b99b8a7f6e5d4c`
403	`permission_denied`	You do not have permission to access this resource. Envelope meta.request_id `d5e6f7a8b9c00c9b8a7f6e5d`
413	`body_too_large`	The request body is too large. Envelope meta.request_id `1a2b3c4d5e6ff6e5d4c3b2a1`
422	`label_invalid_type`	The label field must be a string. Envelope source.pointer `/data/attributes/label` meta.request_id `e1f2a3b4c5d66d5c4b3a2f1e`
422	`no_valid_fields`	The body carries no editable field. Envelope meta.request_id `d0e1f2a3b4c55c4b3a2f1e0d`