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

Create a beneficiary

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 the request sends follows from it:

CLABE (18 digits): bank_code is optional, derived from the prefix.
Card (16 digits): bank_code is optional, derived from the BIN.
Phone/DiMo (10 digits): bank_code is mandatory in the body, since the number alone does not identify the banking institution.

If the account did not exist before, it is registered and the response carries HTTP status 201.

Registering an account that is already active responds with HTTP status 422, with beneficiary_already_registered in the body.

If it exists but is archived, the registration reactivates it and responds with HTTP status 200, with meta.reactivated=true in the body. If the request carries no label, the reactivation keeps the alias the account already had; if it carries one, it replaces it.

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	SPEI code (4 or 5 digits). Required when the detected type is `phone`; ignored for CLABE and card. e.g. `40012`
`label`	string (?–100)	optional	Optional label the account is identified by in the beneficiary list. 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`	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**`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. The possible codes are `account_number_required`, `account_number_invalid_type`, `label_invalid_type`, `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` and `plan_cap_exceeded`. `account_number_invalid_type` and `label_invalid_type` fire when the field arrives as a type other than a string. Every field-level error carries `source.pointer`.	`ErrorResponse`

**Errors from `POST /v1/beneficiaries`**
Status	Code	Example
400	`body_empty`	The request body is empty. Envelope meta.request_id `c1d2e3f4a5b66b5a4f3e2d1c`
400	`invalid_json`	The body is not valid JSON. Envelope meta.request_id `d2e3f4a5b6c77c6b5a4f3e2d`
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	`account_number_invalid_type`	The account_number field must be a string. Envelope source.pointer `/data/attributes/account_number` meta.request_id `a1b2c3d4e5f66f5e4d3c2b1a`
422	`bank_code_required_for_phone`	A `bank_code` is required to register a phone-type beneficiary. Envelope source.pointer `/data/attributes/bank_code` meta.request_id `f6a7b8c9d0e11e0d9c8b7a6f`
422	`beneficiary_already_registered`	A beneficiary with that account number already exists. Envelope source.pointer `/data/attributes/account_number` meta.request_id `b8c9d0e1f2a33a2f1e0d9c8b`
422	`clabe_prefix_not_recognized`	The CLABE prefix does not match any SPEI participant. Envelope source.pointer `/data/attributes/account_number` meta.request_id `a7b8c9d0e1f22f1e0d9c8b7a`
422	`plan_cap_exceeded`	The account's plan does not allow more beneficiaries. Envelope meta.request_id `f4a5b6c7d8e99e8d7c6b5a4f`