Skip to main content

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.

Account Balance Chart
VerbPOST
Urlhttps://api.s.unit.sh/accounts
Required Scopeaccounts-write
Data TypedepositAccount
Timeout (Seconds)5

Attributes

NameTypeDescription
depositProductstringThe name of the deposit product.
tagsobjectOptional. See Tags.
idempotencyKeystringOptional. See Idempotency.

Relationships

NameTypeDescription
customerRequired for individual / business accounts. JSON:API RelationshipThe customer the deposit account belongs to. The customer is either a business or an individual.
customersRequired for joint accounts. Array of JSON:API RelationshipThe 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

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

VerbPOST
Urlhttps://api.s.unit.sh/accounts/:accountId/close
Required Scopeaccounts-write
Data TypedepositAccountClose
Timeout (Seconds)5

Attributes

NameTypeDescription
reasonstringThe reason for closing the account. Either ByCustomer, Fraud, ByBank, or NegativeBalance.
fraudReasonstringOptional. 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).
bankReasonstringOptional. 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

FieldTypeDescription
dataDepositAccountDeposit 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.

VerbPOST
Urlhttps://api.s.unit.sh/accounts/:accountId/reopen
Required Scopeaccounts-write
Timeout (Seconds)5

Response

Response is a JSON:API document.

200 OK

FieldTypeDescription
dataDepositAccountDeposit 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.

VerbPOST
Urlhttps://api.s.unit.sh/accounts/:accountId/freeze
Required Scopeaccounts-write
Timeout (Seconds)5

Attributes

NameTypeDescription
reasonstringThe reason for closing the account. Either Fraud or Other, with a specified reasonText.
reasonTextstringOptional. 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

FieldTypeDescription
dataDepositAccountDeposit 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.

VerbPOST
Urlhttps://api.s.unit.sh/accounts/:accountId/unfreeze
Required Scopeaccounts-write
Timeout (Seconds)5

Response

Response is a JSON:API document.

200 OK

FieldTypeDescription
dataDepositAccountDeposit 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.

VerbGET
Urlhttps://api.s.unit.sh/accounts/{id}
Required Scopeaccounts
Timeout (Seconds)5

Query Parameters

NameTypeDefaultDescription
includestring(empty)Optional. Related resource available to include: customer. See Getting Related Resources

Response

Response is a JSON:API document.

200 OK

FieldTypeDescription
dataDepositAccountThe requested resource after the operation was completed.
includedArray of CustomerArray 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.

VerbGET
Urlhttps://api.s.unit.sh/accounts
Required Scopeaccounts
Timeout (Seconds)5

Query Parameters

NameTypeDefaultDescription
page[limit]integer100Optional. Maximum number of resources that will be returned. Maximum is 10000 resources. See Pagination.
page[offset]integer0Optional. 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]stringAuthorizedOptional. 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
includestring(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

FieldTypeDescription
dataArray of DepositAccountArray of deposit account resources.
includedArray of CustomerArray 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.

VerbPATCH
Urlhttps://api.s.unit.sh/accounts/:accountId
Data TypedepositAccount
Timeout (Seconds)5

Attributes

NameTypeDescription
tagsobjectOptional. See Updating Tags.
depositProductstringOptional. 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

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

VerbGET
Urlhttps://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

VerbGET
Urlhttps://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.

Account Balance Chart
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.

VerbGET
Urlhttps://api.s.unit.sh/account-end-of-day
Required Scopeaccount-end-of-day
Timeout (Seconds)5

Query Parameters

NameTypeDefaultDescription
page[limit]integer100Optional. Maximum number of resources that will be returned. Maximum is 1000 resources.
page[offset]integer0Optional. 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

FieldTypeDescription
dataArray of Account End-Of-DayArray of account end-of-day resources.
metaJSON object that contains pagination dataPagination 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.

VerbPOST
Urlhttps://api.s.unit.sh/accounts/:accountId/relationships/customers
Required Scopeaccounts-write
Timeout (Seconds)5

Attributes

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

FieldTypeDescription
dataDepositAccountThe 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.

VerbDELETE
Urlhttps://api.s.unit.sh/accounts/:accountId/relationships/customers
Required Scopeaccounts-write
Timeout (Seconds)5

Attributes

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

FieldTypeDescription
dataDepositAccountThe 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"
}
}
}
}
}