---
title: "Create a bank key"
method: POST
path: "/v1/banking/bank_keys"
tags: ["Bank key"]
---

# Create a bank key

`POST /v1/banking/bank_keys`

## Request

- Base URL: `https://api.cardda.com`
- URL: `https://api.cardda.com/v1/banking/bank_keys`
- Auth: HTTP bearer

Stores a new set of bank credentials for the company. Cardda encrypts the
secrets at rest; this is the only entry point that accepts plain-text
credentials. Upon creation Cardda runs an asynchronous validation against
the bank — the key starts as `pending`; poll the resource until `status`
flips to `approved` (or `declined`).

A credential can be shared across several companies. If you re-enter a
credential you already own (same `user_id` + `type`, plus `rut` for CL/MX or
`email` for US) and associate it to another company, Cardda attaches that
company to the existing key instead of creating a duplicate — the response is
**`200`** carrying the existing key (vs `201` for a brand-new key).

## Parameters

- `#/paths/~1v1~1banking~1bank_keys/get/parameters/0` (unresolved $ref)

## Request body

- union: The credential must be associated to at least one company: supply either `company_ids` (preferred, multi-company) or the legacy single-company `holder_id`. Sending neither is rejected with `422` (`bank_keys/no_company`).
  - object
    - `password` string, required
    - `type` 'ItauKey' | 'BciKey' | 'Cl::BancoBice::Key' | 'Cl::BancoDeChile::Key' | 'Cl::BancoInternacional::Key' | 'Cl::BancoSantanderChile::Key' | 'Cl::BancoScotiabank::Key' | 'Cl::BancoSecurity::Key' | 'Mx::Stp::Key' | 'Us::Mercury::Key' | 'Pe::BancoBcp::Key', required: Bank-specific subclass of the credential, **without** the `Banking::` prefix — the server prepends it and resolves the constant directly, with no whitelist in between. A value that does not name a real class is **not** a `422`: the constant lookup fails and the request answers **`500`**. Send one of the values below exactly as written, including the `::` separators and the capitalisation.
    - `user_id` string: Firebase user id of the person who provided the credentials.
    - `holder_id` string, uuid, required: The id of the company to associate the credential to (legacy single-company param). Prefer `company_ids` for multi-company credentials; `holder_id` is still accepted as a fallback when `company_ids` is omitted.
    - `company_ids` string[]: Companies to associate the credential to. A credential belongs to a user and can be shared across several companies. On update, this is a full-replacement set of the associated companies.
    - `otp` string: One-time password pushed to the bank (via the crawler) when updating a credential that requires a device/second-factor confirmation. Only read on update (`PATCH`); ignored on create.
    - `card` string, string: The numbers of the company card. Only required in Peruvian Bank Keys
    - `rut` string, string: The user's identifier used at bank's login
  - object
    - `password` string, required
    - `type` 'ItauKey' | 'BciKey' | 'Cl::BancoBice::Key' | 'Cl::BancoDeChile::Key' | 'Cl::BancoInternacional::Key' | 'Cl::BancoSantanderChile::Key' | 'Cl::BancoScotiabank::Key' | 'Cl::BancoSecurity::Key' | 'Mx::Stp::Key' | 'Us::Mercury::Key' | 'Pe::BancoBcp::Key', required: Bank-specific subclass of the credential, **without** the `Banking::` prefix — the server prepends it and resolves the constant directly, with no whitelist in between. A value that does not name a real class is **not** a `422`: the constant lookup fails and the request answers **`500`**. Send one of the values below exactly as written, including the `::` separators and the capitalisation.
    - `user_id` string: Firebase user id of the person who provided the credentials.
    - `holder_id` string, uuid: The id of the company to associate the credential to (legacy single-company param). Prefer `company_ids` for multi-company credentials; `holder_id` is still accepted as a fallback when `company_ids` is omitted.
    - `company_ids` string[], required: Companies to associate the credential to. A credential belongs to a user and can be shared across several companies. On update, this is a full-replacement set of the associated companies.
    - `otp` string: One-time password pushed to the bank (via the crawler) when updating a credential that requires a device/second-factor confirmation. Only read on update (`PATCH`); ignored on create.
    - `card` string, string: The numbers of the company card. Only required in Peruvian Bank Keys
    - `rut` string, string: The user's identifier used at bank's login

## Response `200`

Existing credential — you re-entered a credential you already own and it
was associated to the requested company (or companies) instead of
creating a duplicate. The body is the existing bank key.

- BankKey
  - `id` string, uuid, required
  - `user_id` string, required: Firebase user id of the person who provided the credentials.
  - `status` 'pending' | 'approved' | 'declined' | 'preauthorized', required: Lifecycle of the asynchronous bank validation. A freshly created key is `pending`; poll until it flips to `approved` (or `declined`). A key may also land in `preauthorized`, which requires an extra action before approval (e.g. confirm the logged-in device).
  - `authorization_method` 'token' | 'digipass' | 'device' | 'multipass' | 'santander_pass' | 'bice_pass' | 'itau_pass', nullable: Second factor pinned on this credential. **Almost always `null`** — the method is normally chosen per operation and travels in the body of the authorize / preauthorize calls (see `Bank_authorization`), so it is not stored on the key. Read a `null` here as "not pinned", not as "no second factor".
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required

## Other responses

- `201`: New bank key — `status` is initially `pending`.
- `401`: Unauthorized — missing or invalid bearer token, or `company-id` header not set.
- `403`: Forbidden — the company has not completed its information and KYC.
- `422`: Unprocessable entity — invalid credentials shape, or the credential is already enrolled by a **different** user (`user_id` + `rut`/`email` + `type` uniqueness). Re-entering a credential you already own (with its identifier present) no longer `422`s; it returns `200` with the existing key (see above). Edge case: a **blank-identifier** reconnect (missing `rut` for CL/MX or `email` for US) deliberately skips the association path — as do virtual keys, which always skip it — so it can still `422` on the model's presence/uniqueness validations.

## Changes

- **2026-11-03** `785332193a09`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/cardda/apis/banking-api/changes/v1/banking/bank_keys/post.md)

---

[API](https://skmtc.dev/cardda/apis/banking-api.md) - [All operations](https://skmtc.dev/cardda/apis/banking-api/llms.txt) - [OpenAPI document](https://skmtc.dev/cardda/apis/banking-api/revisions/785332193a09?raw)
