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

# Add a new bank account

> Save the US bank account of someone you want to send money to. Fluz checks the routing number, stores the account securely and returns an ID you use to send.

Add the bank account of the person or business you want to pay. You do this once. After that you send money to it with its `externalPayeeId`.

> [!NOTE]
>
> **This is for someone else's bank account**, the account you are sending money to. To link the user's own bank account as a funding source, see [Linking bank account via Plaid](https://docs.fluz.app/features/link-via-plaid.md).

Why you add the bank account first:

* **Enter bank details once.** The full routing and account number are sent only here. After that you use the `externalPayeeId`.
* **The routing number is checked up front.** A bad routing number is rejected when you add the account, before any money moves.
* **Sensitive data is not returned.** Fluz stores the account number securely and returns only the last four digits.
* **No duplicates.** Adding the same routing and account number again returns the bank account you already saved.
* **One list per account.** Saved bank accounts belong to the Fluz account, so every authorized user on it sees the same list.

Two operations manage saved bank accounts:

* `createExternalPayee` - Add a new bank account
* `externalPayees` - List the saved bank accounts

***

### createExternalPayee

Add a new bank account to the authenticated user's account.

#### Mutation (CreateExternalPayeeInput)

```graphql theme={null}
createExternalPayee(input: CreateExternalPayeeInput!): ExternalPayee
```

**Requires**: `MAKE_PAYOUT_TRANSFER_SEND` scope.

#### Input

| Field | Type | Required | Description |
| :- | :- | :- | :- |
| routingNumber | String! | Yes | The 9-digit ABA routing number of the recipient's bank. Must be a valid ABA number. |
| accountNumber | String! | Yes | The recipient's account number. Digits only, 4 to 17 digits. Remove spaces and dashes before sending. |
| holderName | String! | Yes | The name on the account. Maximum 255 characters. Must contain at least one letter or digit. |
| holderType | ExternalPayeeHolderType! | Yes | `INDIVIDUAL` or `BUSINESS`. |
| emailAddress | String! | Yes | The account holder's email address. Fluz uses it to check if the bank account belongs to a Fluz account. |
| accountType | DepositAccountType | No | `CHECKING` or `SAVING`. Defaults to `CHECKING`. |
| nickname | String | No | A label shown in place of the holder name. Maximum 255 characters. |

#### Response (ExternalPayee)

| Field | Type | Description |
| :- | :- | :- |
| externalPayeeId | ID! | The ID of the saved bank account. Use it as `externalPayeeId` in `createExternalPayout`. |
| holderName | String! | The name on the account |
| holderType | ExternalPayeeHolderType! | `INDIVIDUAL` or `BUSINESS` |
| nickname | String | The label, if one was set |
| status | ExternalPayeeStatus! | `ENABLED` or `REVIEW`. See [Status](#status) below. |
| depositAccountType | DepositAccountType! | `CHECKING` or `SAVING` |
| achRoutingNumber | String! | The ABA routing number |
| destinationAccountNumberLastFour | String! | The last four digits of the account number |
| emailAddress | String | The account holder's email address |
| createdAt | DateTime! | When the bank account was added |

#### Example

```graphql theme={null}
mutation {
	createExternalPayee(
	  input: {
	    routingNumber: "021000021"
	    accountNumber: "123456789"
	    holderName: "Jane Doe"
	    holderType: INDIVIDUAL
	    emailAddress: "jane@example.com"
	    accountType: CHECKING
	    nickname: "Jane - rent"
	  }
	) {
	  externalPayeeId
	  holderName
	  nickname
	  status
	  depositAccountType
	  achRoutingNumber
	  destinationAccountNumberLastFour
	  createdAt
	}
}
```

**Success:**

```json theme={null}
{
	"data": {
	  "createExternalPayee": {
	    "externalPayeeId": "3f1c2b7e-8d4a-4c1e-9f2a-6b5d4e3c2a10",
	    "holderName": "Jane Doe",
	    "nickname": "Jane - rent",
	    "status": "ENABLED",
	    "depositAccountType": "CHECKING",
	    "achRoutingNumber": "021000021",
	    "destinationAccountNumberLastFour": "6789",
	    "createdAt": "2026-10-20T15:30:00.000Z"
	  }
	}
}
```

**Invalid input:**

```json theme={null}
{
	"errors": [
	  {
	    "message": "account_number must contain only digits",
	    "extensions": { "code": "ARG-0001" }
	  }
	]
}
```

#### Error Codes

| Code | Description |
| :- | :- |
| ARG-0002 | A required field is missing |
| ARG-0001 | Invalid input, for example a bad routing number or account number. Also returned when the bank account belongs to the user's own Fluz account. |
| G-0003 | Sending money to bank accounts is not enabled on this account |
| G-0001 | The bank account could not be added, or a server error occurred |

***

### Checking a routing number

There is no separate endpoint to check a routing number. `createExternalPayee` checks it when you add the bank account: it must be 9 digits with a valid ABA check digit. If it fails, the request returns `ARG-0001` and nothing is saved.

To catch typos before you call the API, you can run the same check in your form. Multiply the nine digits by 3, 7, 1, 3, 7, 1, 3, 7, 1 in order and add the results. A valid routing number gives a total that divides evenly by 10.

***

### externalPayees

List the saved bank accounts on the authenticated user's account, newest first.

#### Query

```graphql theme={null}
externalPayees(paginate: OffsetInput): ExternalPayeeConnection!
```

**Requires**: `MAKE_PAYOUT_TRANSFER_SEND` scope.

#### Input (OffsetInput)

| Field | Type | Required | Description |
| :- | :- | :- | :- |
| limit | Int | No | Number of bank accounts per page. Default and maximum is 20. |
| offset | Int | No | Number of bank accounts to skip. Defaults to 0. |

#### Response (ExternalPayeeConnection)

| Field | Type | Description |
| :- | :- | :- |
| externalPayees | \[ExternalPayee] | The saved bank accounts on this page. Same fields as the `createExternalPayee` response. |
| totalCount | Int! | Total number of saved bank accounts on the account |
| hasNextPage | Boolean! | `true` if more are available after this page |

#### Example

```graphql theme={null}
query {
	externalPayees(paginate: { limit: 10, offset: 0 }) {
	  externalPayees {
	    externalPayeeId
	    holderName
	    nickname
	    status
	    destinationAccountNumberLastFour
	  }
	  totalCount
	  hasNextPage
	}
}
```

**Success:**

```json theme={null}
{
	"data": {
	  "externalPayees": {
	    "externalPayees": [
	      {
	        "externalPayeeId": "3f1c2b7e-8d4a-4c1e-9f2a-6b5d4e3c2a10",
	        "holderName": "Jane Doe",
	        "nickname": "Jane - rent",
	        "status": "ENABLED",
	        "destinationAccountNumberLastFour": "6789"
	      }
	    ],
	    "totalCount": 1,
	    "hasNextPage": false
	  }
	}
}
```

**No saved bank accounts:**

```json theme={null}
{
	"data": {
	  "externalPayees": {
	    "externalPayees": [],
	    "totalCount": 0,
	    "hasNextPage": false
	  }
	}
}
```

#### Error Codes

| Code | Description |
| :- | :- |
| G-0001 | Server error |

***

### Status

| Status | What it means |
| :- | :- |
| ENABLED | You can send money to this bank account. |
| REVIEW | The bank account is flagged, usually because a bank returned an earlier payment to it. You can still send money, but `createExternalPayout` refuses with `PT-0009` until you confirm with the user and resend with `acknowledgeReview: true`. |

Only these two are returned. A removed bank account is not listed, and one that can't be used is refused when you add it.

***

### Important Notes

#### createExternalPayee

* Only US bank accounts reachable by ACH are supported. The account type must be `CHECKING` or `SAVING`.
* Adding the same routing and account number again returns the saved bank account. No duplicate is created.
* If a bank account with the same routing and account number was removed earlier, adding it again restores it with its original details. New name, email, or nickname values in the request are not applied.
* You cannot add a bank account that belongs to the authenticated user's own Fluz account.
* Some bank accounts cannot be added. In that case the request fails with a general error.
* The full account number is never returned. Store the `externalPayeeId`, not the bank details.

#### externalPayees

* Returns saved bank accounts for the whole Fluz account, not only those added by the current user.
* Removed bank accounts are not listed.
* Results are sorted newest first.

#### Next step

Send money to the bank account with [`createExternalPayout`](https://docs.fluz.app/features/send-to-a-bank-account), using the `externalPayeeId` and a source cash balance.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.