Deposit Accounts

Deposit Accounts are bank accounts maintained by a financial institution, in which a customer can deposit and withdraw money. Deposit accounts can be checking accounts, savings accounts, or any of several other types.

info

Unit provides a cross-platform suite of flexible and customizable white-label UI components, including an account component and an account activity component. You may embed these components into your app to shorten your time to market and deliver a highly optimized experience to your end customer with minimal engineering investment.

Deposit accounts can belong to an individual customer, multiple customers (joint account) or business customers.

info

Joint accounts are deposit accounts that are assigned to multiple individual customers. Some of the use cases for joint accounts are family members/spouses using it to manage shared funds, or parents creating joint accounts with their children, to provide them with access to banking services and cards.

To create a joint account, you would have to provide an array of two or more Customers as part of the Create Account API call. At least one of the customers must be over 18 years old.

Deposit Products

When creating a deposit account, you are required to select a Deposit Product for the account. The deposit product defines the set of end-customer terms that are applied to the account:

Interest rate paid to the customer
Fees
Limits
Clearing periods for various payments (e.g. check deposit)

You may utilize as many deposit products as you need to make your product work.

There are many use cases for multiple deposit products:

Manage fees and limits to represent different customer tiers (regular / VIP).
Mitigate risk by applying different limits (low / medium / high) and clearing times.
Special purpose accounts (Tax account, Benefits account and many others).

You may move an account between different deposit product (e.g. move an account from "regular" to "VIP") by updating the account.

info

Deposit products are created and updated by Unit's compliance team, since a compliance person must review any changes and make sure they are in line with the relevant regulation.

Create Deposit Account

Creates a deposit account for a Customer (or customers). An account.created event is raised when the call was successful.

Each deposit account is created using a specific deposit product. A deposit product is a predefined set of terms associated with this deposit account (e.g. interest rate, spending limits).

Use checking as the default value for the deposit product field while building your solution in sandbox . Contact Unit to create other deposit products under your organization.

Deposit Account creation request supports Idempotency, ensuring that performing multiple identical requests will have the same effect as performing a single request.

A successful account creation will result in an account in Open status. Later on, accounts can be either frozen, closed and in some cases reopened.

Verb	`POST`
Url	`https://api.s.unit.sh/accounts`
Required Scope	`accounts-write`
Data Type	`depositAccount`
Timeout (Seconds)	`5`

Attributes

Name	Type	Description
depositProduct	string	The name of the deposit product.
tags	object	Optional. See Tags.
idempotencyKey	string	Optional. See Idempotency.

Relationships

Name	Type	Description
customer	Required for individual / business accounts. JSON:API Relationship	The customer the deposit account belongs to. The customer is either a business or an individual.
customers	Required for joint accounts. Array of JSON:API Relationship	The list of customers the deposit account belongs to. Each of the customers is an individual customer and at least one must be over 18 years old.

caution

You must provide exactly one of customer or customers.

Example Request:
curl -X POST 'https://api.s.unit.sh/accounts'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
  "data": {
    "type": "depositAccount",
    "attributes": {
      "depositProduct": "checking",
      "tags": {
        "purpose": "checking"
      },
      "idempotencyKey": "3a1a33be-4e12-4603-9ed0-820922389fb8"
    },
    "relationships": {
      "customer": {
        "data": {
          "type": "customer",
          "id": "45555"
        }
      }
    }
  }
}'

Response

Response is a JSON:API document.

201 Created

Field	Type	Description
data	DepositAccount	The requested resource after the operation was completed.

Example Response:
{
  "data": {
    "type": "depositAccount",
    "id": "42",
    "attributes": {
      "createdAt": "2000-05-11T10:19:30.409Z",
      "name": "Peter Parker",
      "status": "Open",
      "depositProduct": "checking",
      "routingNumber": "812345678",
      "accountNumber": "1000000002",
      "currency": "USD",
      "balance": 10000,
      "hold": 0,
      "available": 10000,
      "tags": {
        "purpose": "checking"
      }
    },
    "relationships": {
      "customer": {
        "data": {
          "type": "customer",
          "id": "45555"
        }
      }
    }
  }
}

Close Account

Closes an account. Closing an account is irreversible and can only be done by an Org user. An account.closed event is raised when the call was successful.

note

Closing an account will also close the cards associated with the account.

info

When closing an account with a balance of $1 or less, the funds will automatically be transferred to your organization's revenue account (see more at Account Low Balance Closure). When closing an account with a balance greater than $1, a check will be mailed to the business or individual address on file.

When closing an account with a negative balance, the balance will be considered a loss, and will be covered from your reserve account

Verb	`POST`
Url	`https://api.s.unit.sh/accounts/:accountId/close`
Required Scope	`accounts-write`
Data Type	`depositAccountClose`
Timeout (Seconds)	`5`

Attributes

Name	Type	Description
reason	string	The reason for closing the account. Either `ByCustomer`, `Fraud`, `ByBank`, or `NegativeBalance`.
fraudReason	string	Optional. The expanded fraud reason for closing the account when `Fraud` is specified as the reason. Can be one of: (`ACHActivity`, `CardActivity`, `CheckActivity`, `ApplicationHistory`, `AccountActivity`, `ClientIdentified`, `IdentityTheft`, `LinkedToFraudulentCustomer`).
bankReason	string	Optional. The expanded bank reason for closing the account when `ByBank` is specified as the reason. Can be one of: (`ProhibitedBusiness`, `MissingCddEdd`, `NonUsOperations`, `SuspectedFraud`). This list is subject to change.

Response

Response is a JSON:API document.

200 OK

Field	Type	Description
data	DepositAccount	Deposit Account resource.

curl -X POST 'https://api.s.unit.sh/accounts/10000/close'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
  "data": {
    "type": "depositAccountClose",
    "attributes": {
      "reason": "ByCustomer"
    }
  }
}'

Reopen Account

Reopens an account.

caution

Reopening an account will not reopen cards associated with the account. Closed cards cannot be reactivated.

note

This API can only be used to reopen accounts which were closed by customers. In order to reopen an account that was closed due to fraud, please contact Unit.

Verb	`POST`
Url	`https://api.s.unit.sh/accounts/:accountId/reopen`
Required Scope	`accounts-write`
Timeout (Seconds)	`5`

Response

Response is a JSON:API document.

200 OK

Field	Type	Description
data	DepositAccount	Deposit Account resource.

curl -X POST 'https://api.s.unit.sh/accounts/10000/reopen'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{}'

Freeze Account

Freezes an account. An account.frozen event is raised when the call was successful. A frozen account behaves like a closed account, with the primary difference being that a frozen state should be temporary, and after evaluation should either be un-frozen, or closed.

note

Freezing an account will also freeze the cards associated with the account.

Verb	`POST`
Url	`https://api.s.unit.sh/accounts/:accountId/freeze`
Required Scope	`accounts-write`
Timeout (Seconds)	`5`

Attributes

Name	Type	Description
reason	string	The reason for closing the account. Either `Fraud` or `Other`, with a specified `reasonText`.
reasonText	string	Optional. The free-text reason for freezing the account (up to 255 characters) when `Other` is specified.

Response

Response is a JSON:API document.

200 OK

Field	Type	Description
data	DepositAccount	Deposit Account resource.

curl -X POST 'https://api.s.unit.sh/accounts/10000/freeze'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
  "data": {
    "type": "accountFreeze",
    "attributes": {
      "reason": "Other",
      "reasonText": "Per request from customer"
    }
  }
}'

Unfreeze Account

Unfreezes an account.

note

Unfreezing an account will also unfreeze the cards associated with the account.

Verb	`POST`
Url	`https://api.s.unit.sh/accounts/:accountId/unfreeze`
Required Scope	`accounts-write`
Timeout (Seconds)	`5`

Response

Response is a JSON:API document.

200 OK

Field	Type	Description
data	DepositAccount	Deposit Account resource.

curl -X POST 'https://api.s.unit.sh/accounts/10000/unfreeze'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{}'

Get by Id

Get a deposit account resource by id.

Verb	`GET`
Url	`https://api.s.unit.sh/accounts/{id}`
Required Scope	`accounts`
Timeout (Seconds)	`5`

Query Parameters

Name	Type	Default	Description
include	string	(empty)	Optional. Related resource available to include: `customer`. See Getting Related Resources

Response

Response is a JSON:API document.

200 OK

Field	Type	Description
data	DepositAccount	The requested resource after the operation was completed.
included	Array of Customer	Array of resources requested by the `include` query parameter.

curl -X GET 'https://api.s.unit.sh/accounts/42' \
-H "Authorization: Bearer ${TOKEN}"

List

List deposit account resources. Paging can be applied.

Verb	`GET`
Url	`https://api.s.unit.sh/accounts`
Required Scope	`accounts`
Timeout (Seconds)	`5`

Query Parameters

Name	Type	Default	Description
page[limit]	integer	100	Optional. Maximum number of resources that will be returned. Maximum is 10000 resources. See Pagination.
page[offset]	integer	0	Optional. Number of resources to skip. See Pagination.
filter[customerId]	string	(empty)	Optional. Filters the results by the specified customer id.
filter[depositProductId]	string	(empty)	Optional. Filters the results by the specified deposit product id.
filter[tags]	Tags (JSON)	(empty)	Optional. Filter Accounts by Tags.
filter[status]	string	Authorized	Optional. Filter Account by its status (`Open`, `Frozen`, or `Closed`). Usage example: filter[status][0]=Closed
filter[fromBalance]	Integer	(empty)	Optional. Filters Accounts that have balance higher or equal to the specified amount (in cents). e.g. `5000`
filter[toBalance]	Integer	(empty)	Optional. Filters Accounts that have balance lower or equal to the specified amount (in cents). e.g. `7000`
include	string	(empty)	Optional. Related resource available to include: `customer`. See Getting Related Resources

curl -X GET 'https://api.s.unit.sh/accounts?page[limit]=20&page[offset]=10' \
-H "Authorization: Bearer ${TOKEN}"

Response

Response is a JSON:API document.

200 OK

Field	Type	Description
data	Array of DepositAccount	Array of deposit account resources.
included	Array of Customer	Array of resources requested by the `include` query parameter.

Example Response:
{
  "data": [
    {
      "type": "depositAccount",
      "id": "42",
      "attributes": {
        "createdAt": "2000-05-11T10:19:30.409Z",
        "name": "Peter Parker",
        "status": "Open",
        "depositProduct": "checking",
        "routingNumber": "812345678",
        "accountNumber": "1000000002",
        "currency": "USD",
        "balance": 10000,
        "hold": 0,
        "available": 10000,
        "tags": {
          "purpose": "tax"
        }
      },
      "relationships": {
        "customer": {
          "data": {
            "type": "customer",
            "id": "45555"
          }
        }
      }
    }
  ]
}

Update

Update a deposit account.

Verb	`PATCH`
Url	`https://api.s.unit.sh/accounts/:accountId`
Data Type	`depositAccount`
Timeout (Seconds)	`5`

Attributes

Name	Type	Description
tags	object	Optional. See Updating Tags.
depositProduct	string	Optional. Name of the selected deposit product (you can get the list of available deposit products using a dedicated API endpoint).

note

Deposit product replacement API is not enabled by default for all customers. Please contact Unit if you need to enable this functionality.

curl -X PATCH 'https://api.s.unit.sh/accounts/42'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
  "data": {
    "type": "depositAccount",
    "attributes": {
      "tags": {
        "purpose": "Tax",
        "trackUserId": null,
        "newTag": "New tag value"
      },
      "depositProduct": "checking"
    }
  }
}'

Response

Response is a JSON:API document.

200 OK

Field	Type	Description
data	DepositAccount	The requested resource after the operation was completed.

Example Response:
{
  "data": {
    "type": "depositAccount",
    "id": "42",
    "attributes": {
      "createdAt": "2000-05-11T10:19:30.409Z",
      "name": "Peter Parker",
      "status": "Open",
      "depositProduct": "checking",
      "routingNumber": "812345678",
      "accountNumber": "1000000002",
      "currency": "USD",
      "balance": 10000,
      "hold": 0,
      "available": 10000,
      "tags": {
        "purpose": "checking"
      }
    },
    "relationships": {
      "customer": {
        "data": {
          "type": "customer",
          "id": "45555"
        }
      }
    }
  }
}

Limits

Verb	`GET`
Url	`https://api.s.unit.sh/accounts/:accountId/limits`
Timeout (Seconds)	`5`

curl -X GET 'https://api.s.unit.sh/accounts/10104/limits' \
-H "Authorization: Bearer ${TOKEN}"

Some monetary transactions (such as originating ACH payments, ATM withdrawals or deposits) are subject to daily and/or monthly amount limits that are defined on the account level. You can read more about the account limits on our limits guide.

The response to this API call includes the defined limits, as well as the current total amounts on each transaction type (under the totalsDaily and totalsMonthly fields), in cents.

note

The daily limits reset at 12:00 a.m. on the timezone of relevant bank. The monthly limits are reset at the same time on the first of each month.

{
  "data": {
    "type": "limits",
    "id": "10104",
    "attributes": {
      "ach": {
        "limits": {
          "dailyDebit": 50000,
          "dailyCredit": 50000,
          "monthlyDebit": 2000000,
          "monthlyCredit": 2000000,
          "dailyDebitSoft": 50000,
          "monthlyDebitSoft": 2000000
        },
        "totalsDaily": {
          "debits": 25000,
          "credits": 10000
        },
        "totalsMonthly": {
          "debits": 800300,
          "credits": 250000
        }
      },
      "card": {
        "limits": {
          "dailyWithdrawal": 2000000,
          "dailyDeposit": 2000000,
          "dailyPurchase": 2000000,
          "dailyCardTransaction": 2000000
        },
        "totalsDaily": {
          "withdrawals": 0,
          "deposits": 0,
          "purchases": 0,
          "cardTransactions": 0
        }
      },
      "checkDeposit": {
        "limits": {
          "daily": 100000,
          "monthly": 2000000,
          "dailySoft": 50000,
          "monthlySoft": 1000000
        },
        "totalsDaily": 0,
        "totalsMonthly": 0
      },
      "wire": {
        "limits": {
          "dailyTransfer": 20000,
          "monthlyTransfer": 20000000,
          "dailyTransferSoft": 0,
          "monthlyTransferSoft": 0
        },
        "totalsDaily": {
          "transfers": 5000
        },
        "totalsMonthly": {
          "transfers": 5000
        }
      },
      "checkPayment": {
        "limits": {
          "dailySent": 20000000,
          "monthlySent": 20000000,
          "dailySentSoft": 10000000,
          "monthlySentSoft": 10000000
        },
        "totalsDaily": {
          "sent": 5000
        },
        "totalsMonthly": {
          "sent": 5000
        }
      }
    }
  }
}

Get Available Deposit Products

Verb	`GET`
Url	`https://api.s.unit.sh/accounts/:accountId/deposit-products`
Timeout (Seconds)	`5`

List of available deposit products compatible to the account.

curl -X GET 'https://api.s.unit.sh/accounts/10104/deposit-products' \
-H "Authorization: Bearer ${TOKEN}"

Example Response:
{
    "data": [
        {
            "type": "accountDepositProduct",
            "attributes": {
                "name": "checking"
            }
        },
        {
            "type": "accountDepositProduct",
            "attributes": {
                "name": "revenue_bank"
            }
        }
    ]
}

Get Account Balance History

List account end-of-day balances history (filtering and paging can be applied).

The account balance history can be used to provide the customer with an overview of their balance across account(s) over time in a visually engaging way, providing insights and creating custom product features around it.

note

The typical cutoff time (end-of-day) is 7PM, but may vary between banks. The exact time and timezone are determined by the partner bank you work with.

Verb	`GET`
Url	`https://api.s.unit.sh/account-end-of-day`
Required Scope	`account-end-of-day`
Timeout (Seconds)	`5`

Query Parameters

Name	Type	Default	Description
page[limit]	integer	100	Optional. Maximum number of resources that will be returned. Maximum is 1000 resources.
page[offset]	integer	0	Optional. Number of resources to skip.
filter[accountId]	string	(empty)	Optional. Filters the results by the specified account id. At least one of `accountId` and `customerId` is required.
filter[customerId]	string	(empty)	Optional. Filters the results by the specified customer id. At least one of `accountId` and `customerId` is required.
filter[since]	ISO Local Date string	(empty)	Optional. Filters the account end-of-day balances after the specified date. e.g. `2021-06-01`
filter[until]	ISO Local Date string	(empty)	Optional. Filters the account end-of-day balances before the specified date. e.g. `2021-07-01`

curl -X GET 'https://api.s.unit.sh/account-end-of-day?page[limit]=10&page[offset]=0&filter[customerId]=10000&filter[accountId]=30317&filter[since]=2020-10-11&filter[until]=2021-10-13' \
-H "Authorization: Bearer ${TOKEN}"

Response

Response is a JSON:API document.

200 OK

Field	Type	Description
data	Array of Account End-Of-Day	Array of account end-of-day resources.
meta	JSON object that contains pagination data	Pagination data includes offset, limit and total (estimated total items).

Example Response:
{
  "data": [
    {
      "type": "accountEndOfDay",
      "id": "4925158",
      "attributes": {
        "date": "2021-07-10",
        "balance": 1000,
        "available": 500,
        "hold": 500
      },
      "relationships": {
        "customer": {
          "data": {
            "type": "customer",
            "id": "10000"
          }
        },
        "account": {
          "data": {
            "type": "account",
            "id": "30317"
          }
        }
      }
    },
    {
      "type": "accountEndOfDay",
      "id": "4925158",
      "attributes": {
        "date": "2021-07-11",
        "balance": 1000,
        "available": 500,
        "hold": 500
      },
      "relationships": {
        "customer": {
          "data": {
            "type": "customer",
            "id": "10000"
          }
        },
        "account": {
          "data": {
            "type": "account",
            "id": "30317"
          }
        }
      }
    }
  ],
  "meta": {
    "pagination": {
      "total": 12,
      "limit": 2,
      "offset": 0
    }
  }
}

Add Account Owners

Add owner or owners to an existing deposit account.

Verb	`POST`
Url	`https://api.s.unit.sh/accounts/:accountId/relationships/customers`
Required Scope	`accounts-write`
Timeout (Seconds)	`5`

Attributes

Name	Type	Description
data	Array	A list of individual customers to be added to the account.

Example Request:
curl -X POST 'https://api.s.unit.sh/accounts/10000/relationships/customers'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
  "data": [
    {
      "type": "customer",
      "id": "10001"
    },
    {
      "type": "customer",
      "id": "10002"
    }
  ]
}'

Response

Response is a JSON:API document.

200 OK

Field	Type	Description
data	DepositAccount	The requested resource after the operation was completed.

Example Response:
{
  "data": {
    "type": "depositAccount",
    "id": "42",
    "attributes": {
      "name": "Peter Parker, April Oneil & Richard Hendricks",
      "createdAt": "2000-05-11T10:19:30.409Z",
      "routingNumber": "812345678",
      "accountNumber": "1000000002",
      "depositProduct": "checking",
      "balance": 10000,
      "hold": 0,
      "available": 10000,
      "tags": {
        "purpose": "checking"
      },
      "currency": "USD",
      "status": "Open"
    },
    "relationships": {
      "customers": {
        "data": [
          {
            "type": "customer",
            "id": "10000"
          },
          {
            "type": "customer",
            "id": "10001"
          },
          {
            "type": "customer",
            "id": "10002"
          }
        ]
      }
    }
  }
}

Remove Account Owners

Remove owner or owners from an existing joint deposit account.

note

At least one of the owners after deletion must be over 18 years old.

note

All cards related to the removed owners will be closed.

Verb	`DELETE`
Url	`https://api.s.unit.sh/accounts/:accountId/relationships/customers`
Required Scope	`accounts-write`
Timeout (Seconds)	`5`

Attributes

Name	Type	Description
data	Array	A list of individual customers to be removed from the account.

Example Request:
curl -X DELETE 'https://api.s.unit.sh/accounts/10000/relationships/customers'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
  "data": [
    {
      "type": "customer",
      "id": "10001"
    }
  ]
}'

Response

Response is a JSON:API document.

200 OK

Field	Type	Description
data	DepositAccount	The requested resource after the operation was completed.

Example Response:
{
  "data": {
    "type": "depositAccount",
    "id": "42",
    "attributes": {
      "name": "Peter Parker",
      "createdAt": "2000-05-11T10:19:30.409Z",
      "routingNumber": "812345678",
      "accountNumber": "1000000002",
      "depositProduct": "checking",
      "balance": 10000,
      "hold": 0,
      "available": 10000,
      "tags": {
        "purpose": "checking"
      },
      "currency": "USD",
      "status": "Open"
    },
    "relationships": {
      "customer": {
        "data": {
          "type": "customer",
          "id": "10000"
        }
      }
    }
  }
}

Deposit Accounts

Deposit Products​

Create Deposit Account​

Attributes​

Relationships​

Response​

201 Created​

Close Account​

Attributes​

Response​

200 OK​

Reopen Account​

Response​

200 OK​

Freeze Account​

Attributes​

Response​

200 OK​

Unfreeze Account​

Response​

200 OK​

Get by Id​

Query Parameters​

Response​

200 OK​

List​

Query Parameters​

Response​

200 OK​

Update​

Attributes​

Response​

200 OK​

Limits​

Get Available Deposit Products​

Get Account Balance History​

Query Parameters​

Response​

200 OK​

Add Account Owners​

Attributes​

Response​

200 OK​

Remove Account Owners​

Attributes​

Response​

200 OK​

Deposit Products

Create Deposit Account

Attributes

Relationships

Response

201 Created

Close Account

Attributes

Response

200 OK

Reopen Account

Response

200 OK

Freeze Account

Attributes

Response

200 OK

Unfreeze Account

Response

200 OK

Get by Id

Query Parameters

Response

200 OK

List

Query Parameters

Response

200 OK

Update

Attributes

Response

200 OK

Limits

Get Available Deposit Products

Get Account Balance History

Query Parameters

Response

200 OK

Add Account Owners

Attributes

Response

200 OK

Remove Account Owners

Attributes

Response

200 OK