> ## 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.

# External payees

Used to save an external bank account as a payee, so you can send money to it from a Fluz cash balance.

### Overview

An external payee is a US bank account that belongs to someone else, for example a contractor, a vendor, or a friend. You save it once on the account, then send ACH payouts to it with `createExternalPayout` using its `externalPayeeId`.

Why payees are saved first:

* **Enter bank details once.** The full routing and account number are sent only when you create the payee. After that you use the `externalPayeeId`.
* **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 existing payee.
* **Account-level list.** Payees belong to the Fluz account, so every authorized user of that account sees the same list.

Two operations manage payees:

* `createExternalPayee` - Add a bank account as a payee
* `externalPayees` - List the payees on the account

> [!NOTE]
>
> External payees are for sending money to **other people's** bank accounts. To
> move money to the user's own bank account, use
> [withdrawals](https://docs.fluz.app/features/move-funds-with-external-accounts.md). To send money to
> another Fluz account, use [Account to Account
> Transfers](https://docs.fluz.app/features/account-to-account-transfers.md).

***

### createExternalPayee

Add an external bank account as a payee on 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 destination bank. Must be a valid ABA number. |
| accountNumber | String! | Yes | The destination account number. Digits only, 4 to 17 digits. Remove spaces and dashes before sending. |
| holderName | String! | Yes | The name on the destination 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 destination 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 payee ID. Use it as `externalPayeeId` in `createExternalPayout`. |
| holderName | String! | The name on the destination account |
| holderType | ExternalPayeeHolderType! | `INDIVIDUAL` or `BUSINESS` |
| nickname | String | The label, if one was set |
| 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 payee 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
	  depositAccountType
	  achRoutingNumber
	  destinationAccountNumberLastFour
	  createdAt
	}
}
```

**Success:**

```json theme={null}
{
	"data": {
	  "createExternalPayee": {
	    "externalPayeeId": "3f1c2b7e-8d4a-4c1e-9f2a-6b5d4e3c2a10",
	    "holderName": "Jane Doe",
	    "nickname": "Jane - rent",
	    "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 external bank accounts is not enabled on this account |
| G-0001 | The bank account could not be added, or a server error occurred |

***

### externalPayees

List the external payees 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 payees per page. Default and maximum is 20. |
| offset | Int | No | Number of payees to skip. Defaults to 0. |

#### Response (ExternalPayeeConnection)

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

#### Example

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

**Success:**

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

**No payees:**

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

#### Error Codes

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

***

### 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 existing payee. No duplicate is created.
* If a payee 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 payees for the whole Fluz account, not only those added by the current user.
* Removed payees are not listed.
* Results are sorted newest first.

#### Next step

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


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