Guide to the Worker Direct Deposit API

The Worker Direct Deposit API lets you read and manage the bank accounts a worker's pay is deposited to. A worker can have up to three accounts: a default account and up to two bank account splits.

Endpoint	What it does
Get a worker's bank accounts	Returns the default account and any bank account splits
Update default bank account	Deprecated. Replaces the default account.
Create or update a bank account split	Sets up split 1 or split 2
Delete a bank account split	Removes a bank account split

Default account and bank account splits

The default account receives whatever is left of each payment after the bank account splits are paid. It's a 100% catch-all, so it has no amount or splitNumber. You can't delete it. The Update default bank account endpoint is deprecated. Use Get a worker's bank accounts and Create or update a bank account split instead.

A bank account split sends a whole-number percentage of each payment (percentPerPayment, 1 to 100) to another account. Percentages don't need to add up to 100: the default account always absorbs the remainder, even when every other account is a percentage-based bank account split. Bank account splits are numbered 1 and 2, and a worker can't have more than two.

The worker must already have a default account before you can add bank account splits.

Creating, updating and deleting bank account splits

Create bank account splits in order. You can't create split 2 until split 1 exists.
Send the full account number when creating a bank account split. Responses only ever include the last four digits (accountNumberLast4). When updating an existing bank account split, accountNumber is optional: leave it out to keep the stored number.
routingNumber must be exactly 9 digits and a real routing number, and accountNumber digits only. Don't send a bank name: Everee determines it from the routing number. See Routing numbers and bank names.
percentPerPayment must be a whole number from 1 to 100. It can be sent as a string or a number, and is always returned as a string.
Duplicate accounts are rejected. You can't add an account that matches one the worker already has.
Deleting a bank account split renumbers the rest. If a worker has splits 1 and 2 and you delete split 1, the account that was split 2 becomes split 1.

Routing numbers and bank names

You don't send a bank name. Everee looks the bank up from routingNumber in the Federal Reserve's routing directory and stores the name the Federal Reserve publishes, for example FIRST CITIZENS BANK & TRUST COMPANY. It's returned as bankName when you read an account.

The routing number must be in the directory. An unknown routing number is rejected with a 400.
Retired routing numbers are rejected. If the bank has a replacement number, the 400 message includes it so you can retry with the new one.
Updating an account only looks the bank up when routingNumber changes. Changing displayName or percentPerPayment on an existing account won't fail because its routing number has since been retired.
bankName is ignored if you send it. Integrations that still include it keep working, and it's no longer required.
The bank name is the Federal Reserve's, so formatting varies. Names are uppercase and punctuation isn't consistent between banks, for example BANK OF AMERICA, N.A. and BANK OF AMERICA N.A. Display it as-is, and don't parse it or compare it between accounts.
The same rules apply when you include a bankAccount while creating a worker. The one difference is that a routing number that fails the check-digit test is rejected with a 409 instead of a 400.
Existing accounts keep the bank name they were saved with until their routing number changes.

Testing in the sandbox

In a sandbox company, any 9-digit routing number is accepted, and the bank name is Demo Bank, even if it isn't a real routing number. To test how your integration handles each outcome, use these reserved routing numbers. They always behave the same way:

Routing number	Result
`999000001`	Accepted. `bankName` is `Test Bank`.
`999000014`	Rejected with a `400`: not a valid bank routing number.
`999000027`	Rejected with a `400`: no longer in use. The message includes the replacement routing number, `999000001`.
`999000009`	Rejected with a `400`: not a valid bank routing number, because the check digit is incorrect.

Reserved numbers only work in sandbox companies. In a production company they're rejected like any other unrecognized routing number.
Match on the 400 status, not the error text. The wording may change.

Fixed dollar amounts on existing bank account splits

This API only accepts percentages. However, a bank account split that was set up with a fixed dollar amount outside this API, such as in the Everee app, still exists. When you read one of those bank account splits, the response includes monthlyDollarAmount instead of percentPerPayment:

{
  "displayName": "Savings",
  "bankName": "MOUNTAIN AMERICA FCU",
  "accountNumberLast4": "4321",
  "routingNumber": "324079555",
  "accountType": "SAVINGS",
  "monthlyDollarAmount": { "amount": "100.00", "currency": "USD" },
  "depositsAllowed": true,
  "splitNumber": 1
}

If you update that bank account split through this API, it's converted to a percentage-based bank account split.

Deposits blocked

depositsAllowed is false when deposits to an account are blocked. Updating the account's details through this API doesn't change that flag.