> ## Documentation Index
> Fetch the complete documentation index at: https://docs.grailpay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Add Bank Account

## Overview

Bank accounts are a core part of ACH transactions in the GrailPay ecosystem. Each transaction involves a **payer**
and **payee**, both of whom must have active, valid bank accounts connected to the application.

If a bank account was not added during initial onboarding (via the registration API), or if you need to attach a new
bank account to an existing user, the **Add Bank Account** API allows you to do so. This endpoint requires the
`user_uuid` of an onboarded **person**, **business**, or **merchant**, which you will include as a path parameter in
your request.

***

## What You'll Need

To add a bank account, you’ll need:

For Manual Account Entry:

* The `user_uuid` of an existing **person**, **business**, or **merchant**
* The bank account details:
* `account_number`
* `routing_number`
* `account_type` (`checking` or `savings`)
* `account_name`

When Using Plaid:

* The `user_uuid` of an existing **person**, **business**, or **merchant**
* A valid `access_token` obtained from the Plaid Link flow
* The `account_id` corresponding to the selected bank account

<Note>
  You also can use the [Bank Link SDK](/docs/technical/bank-link-sdk/overview) to streamline the process of adding
  bank accounts.  You will need to make sure you are either storing the `user_uuid` from onboarding or retrieving it
  from your backend after onboarding to use the SDK to add a bank account to an existing user.
</Note>

***

## Step 1: Determine the Target User

Before you can add a bank account, you must have successfully onboarded a user and obtained their unique `user_uuid`.
This can be from a **Person**, **Business**, or **Merchant** record.

For more details on onboarding:

* [Onboard a Person](/docs/technical/users/onboard-a-person)
* [Onboard a Business](/docs/technical/users/onboard-a-business)
* [Onboard a Merchant](/docs/technical/users/onboard-a-merchant)

***

## Step 2: Prepare Bank Account Details

You’ll need to collect the following information from the user:

* **Account Number** – A 12-digit bank account number.
* **Routing Number** – A valid 9-digit ABA routing number.
* **Account Type** – Either `checking` or `savings`.
* **Account Name** – A user-facing name or label for this account (e.g., "Main Checking").

***

## Step 3: Enable Account & Routing Validation

<Info>
  Enabling account and routing validation at the time of adding a bank account is optional, but strongly recommended
  to help fight fraud and general payment failures.
</Info>

#### Real-Time Validation (Recommended)

To reduce fraud risk and ensure funds can be successfully routed, we recommend enabling real-time bank account validation
during onboarding. This feature is powered by our [Account Intelligence](/docs/risk/bank-accounts/account-intelligence) product,
which provides intelligent validation of routing and account numbers at the time of submission.

To enable this, include an actions object in your onboarding request:

<CodeGroup>
  ```json Success (200) theme={"system"}
  {
      "actions": {
          "account_intelligence": {
              "version": "v3",
              "name_match": true
          }
      }
  }
  ```
</CodeGroup>

<Info>Please note that the Name Match functionality is only available when using V3 of Account Intelligence</Info>

This validation step confirms that the provided routing and account numbers are both valid and correctly formatted. If
name\_match is enabled, it also checks that the account holder’s name aligns with the expected identity. In addition to
these checks, the response includes a **Risk Score** and a set of decisioning insights that explain how the account was
evaluated.

To understand the full structure of the response and how to interpret the results, refer to
our [Account Intelligence](/docs/risk/bank-accounts/account-intelligence#response) documentation.

Although optional, enabling this validation is strongly recommended for all production integrations to reduce failure
rates and improve payout reliability.

***

## Step 4: Attribute Billing to a Merchant

<Info>
  Associating a call to add a bank account with a merchant for billing is not required, but it is strongly recommended if your
  integration supports it, as this allows your team to better track usage for monitoring and billing purposes.
</Info>

If your integration supports **merchant-level billing attribution**, you can associate the bank account creation with a
merchant by passing the `billing_merchant_user_uuid` in your request.

### Billing Attribution

**Field:** `billing_merchant_user_uuid`
**Description:** UUID of a merchant-associated user for billing tracking.

This enables detailed cost attribution across your ecosystem and simplifies billing audits.

***

## Step 5: Make the API Call

To add a bank account, make a `POST` request to the following endpoint, replacing `{uuid}` with the target person's UUID:

```
POST /api/v3/people/{uuid}/bank-accounts
```

For full schema details, refer to
the [Add Bank Account Endpoint](https://api.grailpay.com/api/documentation#/Bank%20Accounts/382621bd16dd23255f6fb5245235a0cd)
in our OpenAPI docs.

***

## Testing

For guidance on testing in Sandbox, see our [Technical Overview](/docs/technical/overview#testing) guide.

***

## Questions?

If you're encountering any issues, please reach out to [support@grailpay.com](mailto:support@grailpay.com).

***