developer.unit-finance.com Open in urlscan Pro
2a05:d014:275:cb02:66df:50b:6e56:a6bf  Public Scan

Form analysis
0 forms found in the DOM

Text Content

Skip to main content
DocsDocs
SearchK
Sign InSign Up
🌜
🌞


Docs
API DocsGuides
 * Overview
   * Introduction
     * Bank Partners
     * Environments
     * SDKs
     * Postman Collection
     * JSON Schema
     * Authentication
     * Scopes
     * Required Fields
     * Retrying API Requests
     * Rate Limits
     * Timeouts
     * Tags
     * Full-Text Search
     * Pagination
     * Idempotency
     * Organization Accounts
     * Data Integrations
     * Changelog
     * Roadmap
   * About JSON:API
 * Webhooks
 * Tokens
 * Applications
 * Customers
 * Deposit Accounts
 * Transactions
 * Payments
 * Cards
 * Check Deposits
 * Fees
 * Rewards
 * Statements
 * Institutions
 * Resources
 * Types
 * Sandbox Testing (Simulations)

Back to unit.co
On this page


INTRODUCTION

Welcome to the Unit API! Our documentation will walk you from the basics
(authentication, request structure) to using and creating financial products
(accounts, cards, payments etc.).

Unit treats each client as a standalone organization. You may log into the Unit
Dashboard to manage your organization's API tokens, users, applications,
customers, accounts and more.

Ready to get started? Sign up here to receive immediate access to our Sandbox
and start building with Unit.

The introduction covers basic concepts you should be familiar with in order to
make the most out of the platform.


BANK PARTNERS#

Unit has 4 bank partners: Piermont Bank, Thread Bank, Blue Ridge Bank, and
Choice Bank; and will continue to add more bank partners. Most features are
available on all bank partners, however some features are not yet available on
all bank partners. When a feature isn't available on all banks, the
documentation will note that.


ENVIRONMENTS#

Our API and Dashboard are available in two environments:

NameDashboard URLAPI
URLSandboxhttps://app.s.unit.sh/https://api.s.unit.sh/Livehttps://app.unit.cohttps://api.unit.co/

The sandbox environment contains special API operations that allow you to easily
test and simulate different activities, from incoming payments to card spend.
You can find the full reference under Simulations.

INFO

Pilot mode is a part of Unit's Live environment and shares the same API and
Dashboard URLs and credentials. Read our pilot guide to learn more about using
the pilot mode to build and test your banking proof of concept.


SDKS#

Unit, with the help of our developer community, maintains open source SDKs in
multiple programming languages. The SDKs are available on Github, and
encapsulate all resources and API endpoints.

TechnologyAuthorTypescriptUnitPythonUnitRubyCommunity

NOTE

If you use a technology / language that isn't covered by an existing SDK, and
would like to use one, please inform your Unit contact.


API COVERAGE#

The SDKs are updated asynchronously, once new capabilities are built into the
API. Note that the SDKs are open source, and you may update them if you need a
certain API endpoint that isn't currently covered. Otherwise, you may reach out
to us and we will make an effort to accommodate your request.


REPORTING ISSUES#

You may report any issues you find with the SDK by creating a Github issue
(TypeScript issues, Python issues). As previously mentioned, the SDKs are open
source, so if you have resolved an issue locally, please raise a PR and we will
publish it, so that other members of the Unit developer community may benefit
from it.


POSTMAN COLLECTION#



You can interact immediately with the Unit API via Postman in two ways.

1) Make API calls yourself. To get started, import the Unit API Postman
Collection into Postman. You can then send any request with the dummy data
provided or customize it.

2) Populate your development environment with a dummy data set. You can import
the Unit API Starter Collection into Postman, then run the full collection.

After making requests with Postman, you can see the API calls you made reflected
in the Unit Dashboard as applications, customers, accounts, transactions, etc.

Both collections contain two variables:

KeyValuetokenYour API Token. You can create it from the API Tokens page in the
Developer section of the Unit Dashboard.server_urlInitially set to the Unit
Sandbox environment (https://api.s.unit.sh/).

For more information, see the following Postman article: Importing Data into
Postman.


JSON SCHEMA#

You can download an archive with JSON Schemas for Unit API.

You can use one of the libraries that generate types from JSON schemas - see
table below for examples of common language specific libraries.

LanguageLibraryNodeJS / TypeScript[json-schema-to-typescript]
(https://www.npmjs.com/package/json-schema-to-typescript)Pythonyacg (Yet Another
Code Generation)PHPphp-code-builder


AUTHENTICATION#

Unit's API uses OAuth 2.0 Bearer Token to authenticate requests. All API calls
must include a bearer token.

CAUTION

An invalid, missing or expired token will result in HTTP 401 Unauthorized
responses.

Example:

GET /accounts HTTP/1.1Host: api.s.unit.shAuthorization: Bearer v2.public.eyJyb2xlIjoib3JnIiwidX...

Copy


TOKENS#

Unit Clients can use 2 types of API tokens:

 * Org API tokens are broad, system level API tokens, that are not restricted to
   a specific end customer.
 * Customer Tokens are end-customer specific, and only allow access to resources
   associated with a specific customer.

When a token is created, it is assigned a set of Scopes The scopes define the
resources that can be accessed using that token, and the access level (read /
write) that will be allowed using that token.

NOTE

Unit recommends using Customer Tokens as a default, for all end-customer related
actions:

 * Customer tokens deny access to all resources that aren't associated with the
   authenticated customer. If a customer token with access to sensitive scopes
   is compromised, the impact is restricted to the specific customer. If an org
   API token with access to sensitive scopes is compromised, the impact could be
   far greater.
 * Customer tokens include built-in Two Factor Authentication (OTP) and expiry
   (customizable, up to 24 hours), so you don't have to implement it.


TWO FACTOR AUTHENTICATION (2FA)#

Unit requires that you take the customer through two factor authentication in a
number of scenarios, detailed in the table below.

Use caseDetailsApplicationsThe customer's phone number must be verified using
OTP (which is a form of 2FA) In order to submit an application. If you choose to
use Unit's application form, we will execute the 2FA on your behalf.Sensitive
ScopesThe customer must be taken through 2FA at least once in the 24 hours prior
to accessing a sensitive scope. We highly recommend using customer tokens for
that purpose.PCI Sensitive dataYou are required to use a valid Unit customer
token in order to access and execute actions that are covered by PCI compliance
(card related data and actions, including activating the card, setting and
changing the PIN, and revealing the card number and CVV2 for virtual cards). You
cannot rely on your own two factor authentication and Org API tokens for that
purpose, unless you are PCI level 1 compliant.

NOTE

If you would like to rely on your own two factor authentication for all non-PCI
related sensitive actions, you may do so. In this scenario, you would use an Org
API token with the relevant scopes to access the Unit API.

Acceptable two factor authentication methods include one time password (OTP)
(through SMS, call or e-mail), biometric authentication and other industry
recognizable methods.

A successful two factor authentication is valid for up to 24 hours, and you
responsible for enforcing the 24 hour expiry and re-authenticating the customer
when needed.


SCOPES#

Scopes define the level of access a token will have to resources in Unit.


A LIST OF ALL SCOPES WITHIN UNIT:#

CAUTION

Scopes that are related to fund movement are considered sensitive, and are
highlighted in the table below. Scopes that require PCI compliance to access are
highlighted in purple.

Any action that requires access to these scopes, must be protected by Two Factor
Authentication. If you follow the best practice and use a Customer Token for
such actions, Unit will execute the authentication for you. If you decide to use
an Org Token, you will have to implement it yourself.

The org token can be used without 2FA for sensitive operations triggered from
the server side.

ResourceRead ScopeWrite ScopeAccessible
UsingApplicationapplicationsapplications-writeOrg API tokenCustomer
Tokencustomer-tokencustomer-token-writeOrg API
tokenCustomerscustomerscustomers-writeOrg API token, Customer TokenCustomer
Tags--customer-tags-writeOrg API token, Customer
TokenAccountsaccountsaccounts-writeOrg API token, Customer Token (exception:
Close Account )Cardscardscards-writeOrg API token, Customer TokenCards
Sensitivecards-sensitivecards-sensitive-writeCustomer
TokenTransactionstransactionstransactions-writeOrg API token, Customer
TokenAuthorizationsauthorizations--Org API token, Customer
TokenStatementsstatements--Org API token, Customer
TokenPaymentspaymentspayments-writeOrg API token, Customer TokenPayments to a
counterparty--payments-write-counterpartyOrg API token, Customer TokenPayments
ACH Debit--payments-write-ach-debitOrg API token, Customer
TokenCounterpartiescounterpartiescounterparties-writeOrg API token, Customer
TokenEventseventsevents-writeOrg API token, Customer
TokenWebhookswebhookswebhooks-writeOrg API tokenAuthorization
Requestsauthorization-requestsauthorization-requests-writeOrg API tokenBatch
Releasesbatch-releasesbatch-releases-writeOrg API tokenCheck
Depositscheck-depositscheck-deposits-writeOrg API token, Customer TokenAccount
End-Of-Dayaccounts--Org API token, Customer TokenReceived
Paymentreceived-paymentsreceived-payments-writeOrg API
tokenChargebackchargebackschargebacks-writeOrg API
tokenRewardrewardsrewards-writeOrg API token

INFO

By default, creating an Org API token through the Create Token Page on the
Dashboard selects the recommended scopes for an Org API token.


REQUIRED FIELDS#

Unless specified otherwise, all the fields in the request payload are required.
Some fields are only required under specific circumstances - these fields are
pointed out throughout the documentation.


RETRYING API REQUESTS#

API requests can fail for many reasons, from network components failures, API
rate limits, timeouts or service incidents. As a best practice, we recommend
implementing a request retrying mechanism with the following attributes:

 1. Only the requests that failed with the following HTTP status codes should be
    retried:
    * 5xx (Server errors)
    * 429 (Rate Limits)
    * 408 (Timeouts)
 2. Retry should have an exponential backoff and/or jitter.
 3. Make sure to add idempotency key where applicable.


RATE LIMITS#

Our rate limit is based on your IP address and is set to 1,000 requests per
minute. The limit applies to each environment (sandbox and live) separately. If
the limit is exceeded, responses will include an HTTP 429 status code along with
a relevant message.


TIMEOUTS#

All of our APIs have timeouts to make sure we fail as soon as possible and allow
you to retry the request>. It is considered good practice to set the same
request timeout for the clients as well. We have two types of timeouts:

 * Short timeout - Most APIs will use the default timeout of 5 seconds
 * Long timeout - Few APIs require longer timeouts, these use a timeout of 120
   seconds

Please advise the relevant API docs to learn what is the timeout for your
request.


TAGS#

To help you manage, categorize and enrich resources, Unit allows you to attach
your own metadata to them in the form of tags (key-value pairs). Common
examples:

 * Attaching a my_customer_id tag to an application with a value that helps you
   connect the application to a unique customer identifier in your app.
 * Attaching a purpose tag to an account with a value such as tax, saving or
   checking.

{    "data": {        "type": "depositAccount",        "attributes": {        /// ...        "tags": {            "purpose": "tax",            "my_account_id": "b6f395c9-e58a-40a5-a5a4-901d603440b9"        }    },    /// ...}

Copy


TAG INHERITANCE#

Some resources are created as a result of you creating a parent resource
(customer and application respectively). They therefore inherit all tags from
their parent resource, as specified in the table below.


TAG SUPPORT#

Resource TypeTag SupportInherited FromApplicationsYesApplication
FormsYesAuthorizationsYesAuthorization RequestAuthorization
RequestsYesCardsYesCheck
DepositsYesCounterpartiesYesCustomersYesApplicationDeposit
AccountsYesFeesYesPaymentsYesStatementsNoTransactionsYesPayment, Authorization
Request


SEARCHING BY TAGS#

The List operation under certain resources (such as Application, Customer or
Payment) supports searching by tags. You can search by passing any number of
key-value pairs. The response will include the resources whose tags contain the
key-value pairs you specified, based on the principles of JSON containment.

Example uses:

 * Assume you attach 5 different tags to all applications you create on Unit.
   One of these tags is a my_customer_id tag that helps you connect every Unit
   application to a unique customer identifier in your app. To search for the
   application that belongs to a known customer, specify a key-value pair in the
   following way: { "my_customer_id": "b6f395c9-e58a-40a5-a5a4-901d603440b9" }
 * Assume you attach 4 different tags to all book transfers you create on Unit.
   Two of these tags are is_loan and number_of_repayments. To search for all
   loans that have four repayments, specify two key-value pairs in the following
   way: { "is_loan": "true", "number_of_repayments": "4" }


UPDATING TAGS#

You can add, update or delete tags from resources with the tags attribute on
their corresponding Update operation (for example, Update Deposit Account).

Unit follows the JSON Merge Patch RFC when updating the tags. In general:

 * To add or update a tag, specify its key and value.
 * To delete a tag, specify its key and null for the value.


TAG CONSTRAINTS#

 * Maximum number of tags per resource: 15
 * Keys and values are case-sensitive
 * Key constraints: 128 characters consisting of letters, numbers and
   underscores
 * Value constraints: 256 characters


FULL-TEXT SEARCH#

The List operation under certain resources (such as Application, Customer or
Transaction) supports full-text search, to help you find the desired resources
more easily.

In particular, you can use full-text search to quickly build better end-customer
experiences. An example would be adding a search box that lets end-customers
search for transactions by merchant name (e.g. 'starbucks') when browsing
transactions under their account.

Full-Text search rules:

 * unquoted text: text without quote marks will be converted into words
   separated by 'And' operators. Example: 'john doe' will search for a resource
   with the value 'john' and the value 'doe'.

 * OR: will be converted into words separated by the 'Or' operator. Example:
   'john or doe' will search for a resource with either the value 'john' or the
   value 'doe'.

 * -: will be converted into the 'Not' operator. Example: 'john -doe' will
   search for a resource with the value 'john' and without the value 'doe'.


PAGINATION#

List operations on all resources (example: List Customers) return a list of
resources.

To page through a long list, use the following two query parameters:

 * page[limit]: Limit the number of resources to be returned (between 1 and
   1000). Defaults to 100 when no value is provided.
 * page[offset]: Number of resources to skip. Defaults to 0 when no value is
   provided.


IDEMPOTENCY#

Some of our API operations support request idempotency, allowing you to call a
sensitive operation multiple times and assume that its work will be done no more
than once. You may use any string of up to 255 characters as an idempotency key
(we recommend UUID version 4).

The guarantee of idempotency is crucial when an API call has failed without a
clear reason and a retry is due. For example, if creating a payment does not
succeed due to a network error, you can safely retry creating the payment,
passing the same idempotency key and assume the payment will occur no more than
once, regardless of the number of calls.

Idempotency keys are guaranteed effective for 48 hours from the time they're
used successfully. After this time window, they will be recycled and existing
keys will therefore be treated as new.

NOTE

Idempotency keys are not shared between different API operations, so you could
potentially use the same idempotency key for different types of operations,
although we do not recommended it.

One exception here is debit card creation for which both physical card creation
and virtual card creation are sharing the idempotency key.


ORGANIZATION ACCOUNTS#

Organization accounts (also known as org accounts) are special-purpose accounts
that Unit sets up to support your activities. Unlike deposit accounts, org
accounts exist on the org level and are not under your customers. Since the
accounts have a special purpose, they only support specific functions that are
relevant to their use case.

Common types of org accounts include:

 * Revenue account: the account that Unit automatically credits with your org's
   interchange, interest and payment revenues. Withdrawals from the Revenue
   account will be done to an account of your choice after it is linked with
   your revenue account. Contact Unit support to set up a link to your chosen
   account/s.
 * Reserve account: the account that Unit automatically debits for a range of
   situations, including disputes and ACH returns. This account requires an
   initial balance to be funded, and monthly recalculation to determine the
   reserve amount required based on risk.
 * Batch account: see Batch Payments

Your org accounts can be accessed from the Unit Dashboard.

NOTE

Some types of organization accounts, such as batch accounts, are designed to be
used for incoming and outgoing payments. Others, such as reserve accounts, offer
limited payments functionality by design.


DATA INTEGRATIONS#

Unit allows its clients access to their raw data, so that they can build their
own reporting solutions and make informed business decisions. This integration
provides a daily upload into an AWS S3 bucket. You can pull the data into your
own data warehouse easily with existing S3 connectors, eliminating the need to
build a sequence of API calls to obtain data. For more information visit the AWS
S3 guide


CHANGELOG#

We publish a monthly review of all the newest updates and features added to the
platform on our Changelog. Subscribe to our newsletter to receive monthly
updates on platform and product changes, directly to your inbox.


ROADMAP#

Check out our continuously updating public Roadmap to see what's planned for the
coming months.

Next
About JSON:API