Add a new bank account

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.

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.

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)

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

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:

{
	"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:

{
	"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

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

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

Success:

{
	"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:

{
	"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, using the externalPayeeId and a source cash balance.

​createExternalPayee

​Mutation (CreateExternalPayeeInput)

​Input

​Response (ExternalPayee)

​Example

​Error Codes

​Checking a routing number

​externalPayees

​Query

​Input (OffsetInput)

​Response (ExternalPayeeConnection)

​Example

​Error Codes

​Status

​Important Notes

​createExternalPayee

​externalPayees

​Next step

createExternalPayee

Mutation (CreateExternalPayeeInput)

Input

Response (ExternalPayee)

Example

Error Codes

Checking a routing number

externalPayees

Query

Input (OffsetInput)

Response (ExternalPayeeConnection)

Example

Error Codes

Status

Important Notes

createExternalPayee

externalPayees

Next step