---
title: "Actualizar external_id de Beneficiary Account"
method: PATCH
path: "/payouts-beneficiary/beneficiary-account/{id_beneficiary_account}/external-id"
tags: ["Beneficiary Accounts"]
---

# Actualizar external_id de Beneficiary Account

`PATCH /payouts-beneficiary/beneficiary-account/{id_beneficiary_account}/external-id`

## Request

- Base URL: `https://api.trytoku.com`
- URL: `https://api.trytoku.com/payouts-beneficiary/beneficiary-account/{id_beneficiary_account}/external-id`
- Auth: API key in header `x-api-key`

Cambia únicamente el `external_id` de una Beneficiary Account, el identificador con que la cuenta se conoce en el sistema de origen.

Se usa cuando la cuenta se creó en Toku antes de existir en el sistema de origen y hay que enlazarlas después. El `external_id` debe ser único entre las cuentas de la Organization: reutilizar uno existente responde `409`.

No toca los datos bancarios ni la verificación de la cuenta, así que no dispara una nueva verificación.

**Límite de tasa:** 1000 solicitudes por hora. Al superarlo, la API responde `429`. Ver [Límites de tasa](/reference/limites-de-tasa).

## Path parameters

- `id_beneficiary_account` string, uuid, required: Identificador de la Beneficiary Account.

## Request body

- PatchBeneficiaryAccountExternalIdPayload: Payload for PATCH external_id only (e.g. HDI flow).
  - `external_id` string, required: Nuevo identificador de la cuenta en el sistema de origen.

## Response `200`

La cuenta con su nuevo external_id.

- PatchBeneficiaryAccountResponse: Response for PATCH external-id and PATCH account-data: beneficiary name, bank details and external_id.
  - `beneficiary_name` string, required: Nombre del Beneficiary dueño de la cuenta.
  - `details` BeneficiaryAccountBankDetailsResponse, required: Bank/account details for PATCH responses.
    - `account_number` string, nullable: Número de la cuenta bancaria. Viene `null` en una cuenta de efectivo, que paga al beneficiario en efectivo y no tiene cuenta bancaria de destino.
    - `bank_code` string, nullable: Código del banco donde está la cuenta. En México son los tres primeros dígitos de la CLABE, así que lo determina el número de cuenta. Viene `null` en una cuenta de efectivo, que no tiene cuenta bancaria de destino.
    - `tokenized_account_number` string, nullable: Token que reemplaza al número de cuenta cuando la cuenta ya fue tokenizada. Viene `null` mientras no lo esté y en una cuenta de efectivo, que no tiene número que tokenizar.
    - `type` 'BANK_ACCOUNT' | 'CASH_ACCOUNT' | 'DEBIT_CARD' | 'CIE_AGREEMENT' | 'INTERNATIONAL_ACCOUNT' | 'BBVA_ACCOUNT' | 'CHECKING_ACCOUNT' | 'VISTA_ACCOUNT' | 'SAVINGS_ACCOUNT', required: Tipo de la cuenta de destino de un Beneficiary Account. Qué valores se aceptan depende del país de la cuenta: en Chile, `CHECKING_ACCOUNT` (cuenta corriente), `VISTA_ACCOUNT` (cuenta vista) y `SAVINGS_ACCOUNT` (cuenta de ahorro); en México, `BANK_ACCOUNT`, cuyo número de cuenta es una CLABE de 18 dígitos; `CIE_AGREEMENT`, un convenio CIE de BBVA de 7 dígitos; `INTERNATIONAL_ACCOUNT`, una cuenta internacional de 20 a 30 dígitos cuyo `bank_code` es el código ABA del banco, de 9 a 11 dígitos; `BBVA_ACCOUNT`, una cuenta BBVA de 10 u 11 dígitos; y `CASH_ACCOUNT` (cuenta de efectivo), que paga al beneficiario en efectivo y por eso no tiene cuenta bancaria de destino. `DEBIT_CARD` quedó como valor heredado y hoy se rechaza en los dos países.
  - `external_id` string, required: Identificador de la cuenta en el sistema de origen.

## Other responses

- `404`: No existe una Beneficiary Account con ese identificador.
- `409`: Ya existe otra Beneficiary Account con ese `external_id`.
- `422`: El cuerpo de la solicitud no cumple el formato esperado.

## Changes

- **2026-11-03** `a6ef070075b1`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/trytoku/apis/toku-api/changes/payouts-beneficiary/beneficiary-account/:id_beneficiary_account/external-id/patch.md)

---

[API](https://skmtc.dev/trytoku/apis/toku-api.md) - [All operations](https://skmtc.dev/trytoku/apis/toku-api/llms.txt) - [OpenAPI document](https://skmtc.dev/trytoku/apis/toku-api/revisions/a6ef070075b1?raw)