VerikoDocs

Type to search. Enter opens the first result.

ES

Create, update, and export beneficiaries

Goal

Build and maintain a whitelist of trusted beneficiary accounts — CLABEs, debit/credit card numbers, and DiMo phone numbers. The whitelist is used by the OCR pipeline to complete the visible digits of a masked account and by your application to validate that a transfer destination is known before sending it.

The list is not a way to find out which of your accounts received a transfer. If the capture does not show the account, send cuenta_beneficiaria in the validation.

Prerequisites

  • An active API key (veriko_…) with the beneficiaries:read and beneficiaries:create permissions.
  • To update: beneficiaries:update. To delete/archive: beneficiaries:delete.
  • To import many accounts at once from a spreadsheet, use POST /v1/beneficiaries/imports — see Bulk beneficiary import.

Steps

1. List existing beneficiaries

Retrieve your full whitelist. The response is not paginated; use with_archived to control the visibility of archived accounts.

# Active accounts only
curl 'https://api.veriko.mx/v1/beneficiaries?with_archived=0' \
  -H 'Authorization: Bearer veriko_••••'
{
  "data": [
    {
      "type": "beneficiary",
      "id": "42",
      "attributes": {
        "account_number": "012180004412345678",
        "account_type": "clabe",
        "bank_code": "40012",
        "bank_name": "BBVA MEXICO",
        "label": "Proveedor Alpha",
        "status": "active",
        "created_at": "2025-01-10T09:00:00Z"
      }
    }
  ]
}

2. Add a beneficiary

The list includes meta.plan_cap.max and meta.plan_cap.current: the plan cap and active count, regardless of the with_archived filter. max=-1 means uncapped. At capacity, the app and bot block adding an account and ask for an account to be archived to free up space. The server returns 422 plan_cap_exceeded; reactivating an archived account also takes a slot. Editing a label or archiving an account remains allowed.

curl -X POST 'https://api.veriko.mx/v1/beneficiaries' \
  -H 'Authorization: Bearer veriko_••••' \
  -H 'Content-Type: application/json' \
  -d '{
    "label": "Proveedor Beta",
    "account_number": "646180157000001234"
  }'

The creation fields are account_number (required) and label (optional, 100 characters at most). The account type is not sent: it is deduced from the length of account_number, with 18 digits for a CLABE, 16 for a card and 10 for a DiMo mobile number.

For a DiMo mobile number, bank_code is mandatory: the number alone does not identify the institution, and you can find it in the bank list. For a CLABE or a card the code is derived from the prefix or the BIN, and whatever you send is ignored.

Response 201:

{
  "data": {
    "type": "beneficiary",
    "id": "87",
    "attributes": {
      "account_number": "646180157000001234",
      "account_type": "clabe",
      "bank_code": "90646",
      "bank_name": "STP",
      "label": "Proveedor Beta",
      "status": "active",
      "created_at": "2025-04-22T14:15:00Z"
    }
  }
}

3. Update a beneficiary

Change the label (label). If you send a new account_number, the account type and the bank are deduced again with the same rules as at creation. On a DiMo mobile number you can also change only the bank_code.

curl -X PUT 'https://api.veriko.mx/v1/beneficiaries/87' \
  -H 'Authorization: Bearer veriko_••••' \
  -H 'Content-Type: application/json' \
  -d '{ "label": "Proveedor Beta S.A." }'

Returns 200 with the updated record.

4. Archive a beneficiary

Soft-delete an account to remove it from the active list without permanently deleting the history. If you register the same number again, through the API, the app, the bot or an import, the archived account is reactivated instead of duplicated and keeps its alias unless you send a new one.

curl -X DELETE 'https://api.veriko.mx/v1/beneficiaries/87' \
  -H 'Authorization: Bearer veriko_••••'

Returns 204. To view archived accounts: GET /v1/beneficiaries?with_archived=1.

5. Export the list

Download your complete beneficiary list as a file for audit or system sync:

curl 'https://api.veriko.mx/v1/beneficiaries/export?format=csv' \
  -H 'Authorization: Bearer veriko_••••' \
  --output beneficiarios.csv

Use format=xlsx for a spreadsheet. The export respects the same with_archived filter as the list endpoint.

What's next