NAV

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? Contact us to request sandbox access and we'll get your organization set up. We will send you a welcome email that includes your dashboard credentials, a front-end code sample (React) and a server code sample (Node.js).

This introduction section describes our environments, authentication and other general topics.

Environments

Our API and Dashboard are available in two environments:

Name Dashboard URL API URL
Sandbox https://app.s.unit.sh/ https://api.s.unit.sh/
Production Please contact Unit Please contact Unit

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.

Postman Collection

You can interact immediately with the Unit API via Postman.

To get started, import the Unit API Postman Collection into Postman, either by link or by downloading and importing the file. For more information, see the following under the Postman help: Importing Data into Postman.

The collection contains two variables:

Key Value
token Your API Token. You can create it from the API Tokens page on the Unit Dashboard.
server_url Initially set to the sandbox environment.

JSON Schema

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

Authentication

Example

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

Unit's API uses OAuth 2.0 Bearer Token to authenticate requests. All API calls must include a bearer token. You can create an API Token from the API Tokens page on the Unit Dashboard.

When creating an API Token you would need to select the scopes of the token, by default the Create Token Page selects the recommended scopes for an API token.

The unselected scopes are sensitive scopes that are related to funds movement and cards creation. Unit recommends that for those scopes you would use a Customer Token.

Customer Token

A secure alternative to a broad bearer token is a customer-specific bearer token, also known as Customer Token. This type of token is limited to resources under a particular customer (accounts, transactions, statements and more). For instructions, see Customer Token.

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 production) separately. If the limit is exceeded, responses will include an HTTP 429 status code along with a relevant message.

Tags

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

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:

Tag Inheritance

Unit currently allows you to attach tags to the following resources: application, deposit account and payment.

Two additional resources- customer and transaction- are always created as a result of you creating a parent resource (application and payment respectively). They therefore inherit all tags from their parent resource:

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:

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:

Tag Constraints

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:

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:

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.

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 existing on the org level and not under your customers.

Common types of org accounts include:

Your org accounts can be accessed from the Unit Dashboard. You may also access data in org accounts programmatically, in the same way that you access data in deposit accounts (for example, by calling List Transactions).

About JSON:API

Unit's API is REST-based and follows the JSON:API specification.

JSON:API specifies how a client should request resources to be fetched or modified, and how a server should respond to those requests. Resources in Unit include applications, customers, cards, accounts, transactions and more.

JSON:API is designed to minimize both the number of requests and the amount of data transmitted between clients and servers. This efficiency is achieved without compromising readability, flexibility, or discoverability.

JSON:API requires the use of the JSON:API media type (application/vnd.api+json) for exchanging data.

Request and Response Structure

Single Resource Object Example:

{
  "data": {
    "type": "individualCustomer",
    "id": "1",
    "attributes": {
      // ... this customer's attributes
    },
    "relationships": {
      // ... this customer's relationships
    }
  }
}

Array of Resource Objects Example:

{
    "data": [
        {
            "type": "individualCustomer",
            "id": "1",
            "attributes": {
              // ... this customer's attributes
            },
            "relationships": {
              // ... this customer's relationships
            }
        }, {
           "type": "businessCustomer",
           "id": "2",
           "attributes": {
             // ... this customer's attributes
           },
           "relationships": {
             // ... this customer's relationships
           }
       }
   ]       
}

All JSON:API requests and responses are JSON documents.

A document MUST contain one of the following top-level members:

Primary data MUST be either:

Resource Object

Resource Example:

{
  "type": "individualCustomer",
  "id": "53",
  "attributes": {
    "createdAt": "2020-05-12T19:41:04.123Z",
    "fullName": {
      "first": "Peter",
      "last": "Parker"
    },
    "nationality": "US",
    "ssn": "721074426",
    "address": {
      "street": "20 Ingram St",
      "street2": null,
      "city": "Forest Hills",
      "state": "NY",
      "postalCode": "11375",
      "country": "US"
    },
    "dateOfBirth": "2001-08-15",
    "email": "peter@oscorp.com",
    "phone": {
      "countryCode": "1",
      "number": "15555555"
    }
  },
  "relationships": {
    // ... relationships
  }
}

JSON:API documents may contain resource objects to represent objects in the business domain. Unit's resources include applications, customers, cards, accounts, transactions and more.

A resource object MUST contain both the id and the type members.

In addition, a resource object MAY contain these members:

Relationships

Resource with relationships example:

{
  "type": "depositAccount",
  "id": "50",
  "attributes": {
   // ...
  },
  "relationships": { // relationships object
    "customer": { // relationship object
      "data": { // resource linkage with single resource identifier
        "type": "businessCustomer",
        "id": "39"
      }
    }
  }
}

The relationships object describes the relationship between the current resource and other resources. Each member of the relationships object represents one reference.

In this example, we describe the relationship between a DepositAccount and the customer it belongs to.

Relationship

A “relationship object” MUST contain a data member with one of the following:

curl -X GET 'https://api.s.unit.sh/cards/41?include=customer,account' \
-H "Authorization: Bearer ${TOKEN}"

Get operations on certain resources (such as Card) contain an include query parameter that helps you get multiple related resources within the response. You may specify one or more relationships (comma-separated- see example). The response will then contain an included key with the related resources.

The ability to get related resources helps you turn multiple API calls into one. The result is cleaner code and no data integrity questions that usually arise when making multiple API calls at slightly different points in time.

Resource with included example:

{
  "data": {
    "type": "individualDebitCard",
    "id": "41",
    "attributes": {
      "createdAt": "2020-11-30T16:00:52.919Z",
      "last4Digits": "0261",
      "expirationDate": "2023-11",
      "status": "ClosedByCustomer"
    },
    "relationships": {
      "customer": {
        "data": {
          "type": "customer",
          "id": "10156"
        }
      },
      "account": {
        "data": {
          "type": "account",
          "id": "10075"
        }
      }
    }
  },
  "included": [
    {
      "type": "depositAccount",
      "id": "10075",
      "attributes": {
        "name": "April Oneil",
        "createdAt": "2020-11-30T15:56:59.670Z",
        "routingNumber": "812345678",
        "accountNumber": "1000000075",
        "depositProduct": "checking",
        "balance": 144785,
        "hold": 0,
        "available": 144785,
        "tags": {},
        "currency": "USD"
      },
      "relationships": {
        "customer": {
          "data": {
            "type": "customer",
            "id": "10156"
          }
        }
      }
    },
    {
      "type": "individualCustomer",
      "id": "10156",
      "attributes": {
        "createdAt": "2020-11-30T15:54:22.788Z",
        "fullName": {
          "first": "April",
          "last": "Oneil"
        },
        "ssn": "110000002",
        "address": {
          "street": "20 Ingram St",
          "city": "Forest Hills",
          "state": "CA",
          "postalCode": "11375",
          "country": "US"
        },
        "dateOfBirth": "2001-08-10",
        "email": "april@baxter.com",
        "phone": {
          "countryCode": "1",
          "number": "5555555555"
        },
        "soleProprietorship": false,
        "tags": {}
      },
      "relationships": {
        "application": {
          "data": {
            "type": "application",
            "id": "10186"
          }
        },
        "org": {
          "data": {
            "type": "org",
            "id": "1"
          }
        }
      }
    }
  ]
}

Errors

Unit's API uses HTTP Status Codes to communicate whether a request has been successfully processed. A request may stop processing as soon as a problem is encountered, or it may continue processing and encounter multiple problems. In either case, the response will contain all available errors.

An “error object” MUST contain a title and the HTTP status code members with one or more of the following:

Webhooks

Unit uses webhooks to notify your application when an event occurs.

Example events: Application denied, Customer created, Transaction created. See Events for the full list.

When one of those events occurs, an HTTP POST request is sent to the webhook's configured URL, allowing you to act upon it.

Use Unit's Dashboard to create and manage your webhooks.

Securing your webhooks

Example of a NodeJS server verifying webhook payload

const express = require('express')
var crypto = require('crypto')
const app = express()
const port = 4000

app.post('/my-webhhok', (request, response) => {
  response.send('request passed signature validation...')
})

app.use(express.json());
app.use(express.urlencoded({
    extended: true
}));

app.use((request, response, next) => {
    var signature = request.header("x-unit-signature")
    var hmac = crypto.createHmac('sha1', <your secret>)
    hmac.update(JSON.stringify(request.body))

    if(hmac.digest('base64') == signature) {
        next()
    }
    else {
        response.status(500).send("Signatures didn't match!")
    }
  })


app.listen(port, (err) => {
  console.log(`server is listening on ${port}`)
})

Ensure your server is only receiving the expected Unit requests.

Once your server is configured to receive payloads, it'll listen for any payloads sent to the endpoint you configured.

For security reasons, you probably want to verify that the payloads are coming from Unit.

To verify the payloads when creating a webhook you can set up a secret token which Unit will use to sign the payloads.

Setting up your secret token

You'll need to set up your secret token in two places: Unit dashboard and your server. To set your token in Unit Dashboard:

  1. Navigate to Webhooks on the left side menu.
  2. Click on create and fill up the token field.

Verifying payloads from Unit

If your secret token is set, Unit will use it to create a hash signature with the entire body of the webhook request.

This hash signature, encoded with base64 is passed along with each request in the headers as X-Unit-Signature.

Unit uses an HMAC SHA1 to compute the hash.

Testing

To test the Webhook functionality you can use https://webhook.site. This site will let you generate a unique URL to use for your Webhook and then capture incoming requests, allowing you to examine the event's contents.

Another alternative is to use https://ngrok.com which enables you to expose a port on your development machine to the internet.

Plaid Integration

Unit and Plaid have partnered to help Unit clients move funds between accounts on Unit and any external bank account. To get started, see add Unit to your app under the Plaid docs.

Once you authenticate an external bank account with Plaid, you can pass the resulting Plaid token to certain Unit API endpoints. Unit will then inspect the Plaid token for the full details of that external account (routing number, account number & more) and treat it as a counterparty in payments.

Unit API endpoints that can receive a Plaid token are:

How-To Guides

Below are common use cases for the Plaid integration and steps you'll need to follow to build them:

Helping a Customer Fund Their Account

Example: you've just created a deposit account for an individual customer. You'd like to help them fund it from a bank account that they own on another institution (e.g. Chase).

Follow these steps:

  1. Use Plaid to authenticate the customer's account on Chase
  2. Create a counterparty with the Plaid Token
  3. Initiate an ACH Debit payment with the newly created counterparty to pull funds from Chase

Helping a Customer Withdraw Funds from Their Account

Example: a business customer holds an account with you and wants to withdraw funds from it into a bank account on another institution (e.g. Wells Fargo).

Follow these steps:

  1. Use Plaid to authenticate the customer's account on Wells Fargo
  2. Create a counterparty with the Plaid Token
  3. Initiate an ACH Credit payment with the newly created counterparty to send funds to Wells Fargo

Helping a Customer Bill a Third Party

Example: a business customer holds a deposit account with you and wants to bill a client that has an account on another institution (e.g. Bank of America) for an invoice.

Follow these steps:

  1. Use Plaid to authenticate the third party account on Bank of America
  2. Create a counterparty with the Plaid Token
  3. Initiate an ACH Debit payment with the newly created counterparty to pull funds from Bank of America

Helping a Customer Pay a Third Party

Example: a business customer holds a deposit account with you and wants to pay a vendor that has an account on another institution (e.g. Bank of America)

Follow these steps:

  1. Use Plaid to authenticate the third party account on Bank of America
  2. Create a counterparty with the Plaid Token
  3. Initiate an ACH Credit payment with the newly created counterparty to send funds to Bank of America

Customer Token

Unlike the broader API Token, the Customer Token is limited to resources under a particular customer (accounts, transactions, statements and more).

By using a customer token, you may grant access only to a limited set of operations exposed by Unit's API.

Unit defines that some operations require two-factor authentication, as described in the Scopes section below.

Operations under the following resources may be called using a Customer Token:

How-To Guides

Below are common use cases for using a customer token and steps you’ll need to follow to build them:

Allowing a customer to view their debit cards

Example: Your application contains a page that displays the customer's debit cards.

Listing all cards of a customer example:

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

Follow these steps:

  1. Call the Create customer token with the cards scope included.
  2. Call the List Cards operation and pass the customer token received in step #1 in the request Authorization header. No need to pass the filter[customerId] parameter since the token handles the filtering.

Allowing a customer to create a new debit card (requires two-factor authentication)

Example: Your application contains a page that enables debit card creation.

Creating a new debit card example:

curl -X POST 'https://api.s.unit.sh/cards' \
-H "Content-Type: application/vnd.api+json" \
-H "Authorization: Bearer ${CUSTOMER_TOKEN}" \
--data-raw '{
  "data":{
    "type":"individualDebitCard",
     "attributes": {
         "shippingAddress": {
             "street": "5230 Newell Rd",
             "city": "Palo Alto",
             "state": "CA",
             "postalCode": "94303",
             "country": "US"
         }
     },
     "relationships": {
         "account": {
             "data": {
                 "type": "depositAccount",
                 "id": "10001"
             }
         }
     }
  }
}
'

Follow these steps:

  1. The customer clicks the Create Debit Card button on their cards application page.
  2. Call the Create Customer Token Verification. This will return a verification token and will send the customer a verification code.
  3. Allow the customer to enter the verification code they received.
  4. Call the Create customer token with the cards-write scope included as well as the verification token received in step #2 and the verification code entered by the customer in step #3.
  5. Call the Create Individual Debit Card and pass the customer token received in step #4 in the request Authorization header.

Scopes

A Scope defines the level of access a customer will have to a specific resource.

For example: the accounts scope below provides read level access to account related data.

The following scopes are available when creating a customer token:

Resource Read Scope Write Scope
Customers customers customers-write
Customer Tags customer-tags-write
Accounts accounts accounts-write
Cards cards cards-write
Cards Sensitive cards-sensitive cards-sensitive-write
Transactions transactions transactions-write
Authorizations authorizations
Statements statements
Payments payments payments-write
Payments to a counterparty payments-write-counterparty
Payments ACH Debit payments-write-ach-debit
Counterparties counterparties counterparties-write

Create Customer Token

Example Request (two-factor authentication not required):

curl -X POST 'https://api.s.unit.sh/customers/8/token' \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: Bearer ${TOKEN}' \
--data-raw '{
  "data":{
    "type":"customerToken",
    "attributes": {
      "scope": "customers customer-token-create accounts-create accounts"
    }
  }
}
'

Listing all accounts of a customer:

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

Create a bearer token for a particular customer. The returned token can be used in the Authorization header as a secure alternative to the broader API token.

A Customer Token can only interact with resources under a particular customer. As an example, calling List Transactions with a customer bearer token will return only transactions within accounts under that particular customer.

Verb POST
Url https://api.s.unit.sh/customers/:customerId/token
Required Scope customer-token-write
Data Type customerToken

Example Request (two-factor authentication required)

{
  "data":{
    "type":"customerToken",
    "attributes": {
      "scope": "customers customer-token-create accounts-create accounts",
      "verificationToken": "i8FWKLBjXEg3TdeK93G3K9PKLzhbT6CRhn/VKkTsm....",
      "verificationCode": "203130"
    }
  }
}

Attributes

Name Type Description
scope string list of Scopes separated by spaces.
verificationToken string Received as a response from Create Customer Token Verification. Required if scope includes a scope which require two-factor authentication.
verificationCode string 6 digits code sent to the customer through the desired channel. Required if the scope attribute includes a scope which requires two-factor authentication.

Response

Example Response:

{
  "data": {
    "type": "customerBearerToken",
    "attributes": {
      "token": "v2.public.eyJyb2xlIjoiY3VzdG9tZX...",
      "expiresIn": 86400
    }
  }
}

Response is a JSON:API document.

201 Created

Field Type Description
data.attributes.token The token issued for the customer.
data.attributes.expiresIn The lifetime of the token (in seconds).

Create Customer Token Verification

In order to increase security and prevent token theft, Unit supports two-factor authentication when creating a customer token.

When creating a customer token that contains a scope which requires two-factor authentication (see Scopes), it is required to first create a verification challenge that will be sent to the customer.

The challenge is a six digits code and is valid for 10 minutes after its creation.

Create a token verification:

curl -X POST 'https://api.s.unit.sh/customers/10001/token/verification' \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: Bearer ${TOKEN}' \
--data-raw '{
  "data":{
    "type":"customerTokenVerification",
    "attributes": {
      "channel": "sms"
    }
  }
}'
Verb POST
Url https://api.s.unit.sh/customers/:customerId/token/verification
Required Scope customers
Data Type customerTokenVerification

Attributes

Name Type Description
channel string send a verification code to the customer through one of the following channels sms or call.

Example Response:

{
  "data": {
    "type": "customerTokenVerification",
    "attributes": {
      "verificationToken": "i8FWKLBjXEg3TdeK93G3K9PKLzhbT6CRhn/VKkTsm...."
    }
  }
}

201 Created

Field Type Description
verificationToken string The generated verification token . It should be passed back to Create Customer Bearer Token along with the verification code the customer received on the specified channel

Applications

To onboard an end-customer, create an Application resource.

Unit supports two types of applications, depending on the type of end-customer: individual and business. Once you create an application, you will receive a response containing its status and a list of required documents.

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

Application Statuses

The final statuses for an application are Approved or Denied. Once an application is approved, a Customer resource will be created and associated with the application resource. The new created customer resources will be referenced in the relationships object.

In most cases, an application will reach one of these final statuses immediately after creation, without requiring any documents.

In some cases, documents will be required and the application will enter an AwaitingDocuments status. Once you upload all the required documents, Unit will use the information provided to approve or deny the application. The decision may take seconds in some cases and up to two hours in other cases (when a manual review is required). Once the process is complete, you will receive a webhook containing the result.

An application can also be evaluated asynchronously, in which case its status will be Pending as long as the evaluation process is running. Once the process is complete, the status will change to either Approved, Denied or AwaitingDocuments and the relevant webhook event will be fired (see Pending status description below)

Below is a diagram describing the lifecycle of an application:

(.Get 1)

Below are all application statuses and their descriptions:

Status Description
AwaitingDocuments Certain documents are required for the process to continue. You may upload them via Upload Document.
PendingReview The application is pending review by Unit.
Pending The application is being evaluated asynchronously and a result should be available shortly. Listen for webhooks (application.denied, customer.created and application.awaitingdocuments) for the final result, or periodically query the application with Get by Id).
Approved The application was approved. A Customer resource was created.
Denied The application was denied. A Customer resource will not be created.

Create Individual Application

Create an application for an individual end-customer.

Example Request:

curl -X POST 'https://api.s.unit.sh/applications' \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: Bearer ${TOKEN}' \
--data-raw '{
  "data": {
    "type": "individualApplication",
    "attributes": {
      "ssn": "721074426",
      "fullName": {
        "first": "Peter",
        "last": "Parker"
      },
      "dateOfBirth": "2001-08-10",
      "address": {
        "street": "20 Ingram St",
        "city": "Forest Hills",
        "state": "NY",
        "postalCode": "11375",
        "country": "US"
      },
      "email": "peter@oscorp.com",
      "phone": {
        "countryCode": "1",
        "number": "5555555555"
      },
      "ip": "127.0.0.1",
      "soleProprietorship": true,
      "ein": "123456789",
      "dba": "Piedpiper Inc",
      "tags": {
        "userId": "106a75e9-de77-4e25-9561-faffe59d7814"
      },
      "idempotencyKey": "3a1a33be-4e12-4603-9ed0-820922389fb8"
    }
  }
}'
Verb POST
Url https://api.s.unit.sh/applications
Required Scope applications-write
Data Type individualApplication

Attributes

Name Type Description
ssn string SSN of the individual (numbers only). Either an SSN or a passport number is required.
passport string Passport number of the individual. Either an SSN or a passport is required.
nationality ISO31661-Alpha2 string Required on passport only. Two letters representing the individual nationality. (e.g. “US”).
fullName FullName Full name of the individual.
dateOfBirth RFC3339 Date string Date only (e.g. "2001-08-15").
address Address Address of the individual.
phone Phone Phone number of the individual.
email string Email address of the individual.
ip string IP address of the end-customer creating the application.
soleProprietorship boolean Optional. Default: false. Indicates whether the individual is a sole proprietor.
ein string Optional. If the individual is a sole proprietor who has an Employer Identification Number, specify it here. Not all sole proprietors have an EIN, so this attribute is optional, even when soleProprietorship is set to true.
dba string Optional. If the individual is a sole proprietor who is doing business under a different name, specify it here. This attribute is optional, even when soleProprietorship is set to true.
tags object See Tags. Tags that will be copied to the customer that this application creates (see Tag Inheritance).
idempotencyKey string See Idempotency.

Response

Response is a JSON:API document.

Example Response:

{
  "data": {
    "type": "individualApplication",
    "id": "53",
    "attributes": {
      "createdAt": "2020-01-14T14:05:04.718Z",
      "fullName": {
        "first": "Peter",
        "last": "Parker"
      },
      "ssn": "721074426",
      "address": {
        "street": "20 Ingram St",
        "street2": null,
        "city": "Forest Hills",
        "state": "NY",
        "postalCode": "11375",
        "country": "US"
      },
      "dateOfBirth": "2001-08-10",
      "email": "peter@oscorp.com",
      "phone": {
        "countryCode": "1",
        "number": "5555555555"
      },
      "status": "AwaitingDocuments",
      "evaluationOutcome": "Approved",
      "ip": "127.0.0.1",
      "soleProprietorship": true,
      "ein": "123456789",
      "dba": "Piedpiper Inc",
      "tags": {
        "userId": "106a75e9-de77-4e25-9561-faffe59d7814"
      }
    },
    "relationships": {
      "org": {
        "data": {
          "type": "org",
          "id": "1"
        }
      },
      "documents": {
        "data": [
          {
            "type": "document",
            "id": "1"
          },
          {
            "type": "document",
            "id": "2"
          }
        ]
      }
    }
  },
  "included": [
    {
      "type": "document",
      "id": "1",
      "attributes": {
        "documentType": "AddressVerification",
        "status": "Required",
        "name": "Peter Parker",
        "description": "Please provide a document to verify your address. Document may be a utility bill, bank statement, lease agreement or current pay stub.",
        "address": {
          "street": "20 Ingram St",
          "street2": null,
          "city": "Forest Hills",
          "state": "NY",
          "postalCode": "11375",
          "country": "US"
        }
      }
    },
    {
      "type": "document",
      "id": "2",
      "attributes": {
        "documentType": "IdDocument",
        "status": "Required",
        "name": "Peter Parker",
        "description": "Please provide a copy of your unexpired government issued photo ID which would include Drivers License or State ID.",
        "dateOfBirth": "2001-08-10"
      }
    }
  ]

}

201 Created

Field Type Description
data IndividualApplication The newly created resource.
included Array of ApplicationDocument Resource Required documents for this application. Each document resource includes the document status.

Create Business Application

Create an application for a business end-customer.

Example Request:

curl -X POST 'https://api.s.unit.sh/applications' \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: Bearer ${TOKEN}' \
--data-raw '{
  "data": {
    "type": "businessApplication",
    "attributes": {
      "name": "Pied Piper",
      "address": {
        "street": "5230 Newell Rd",
        "city": "Palo Alto",
        "state": "CA",
        "postalCode": "94303",
        "country": "US"
      },
      "phone": {
        "countryCode": "1",
        "number": "5555555555"
      },
      "stateOfIncorporation": "DE",
      "ein": "123456789",
      "entityType": "Corporation",
      "ip": "127.0.0.1",
      "website": "https://www.piedpiper.com",
      "contact": {
        "fullName": {
          "first": "Richard",
          "last": "Hendricks"
        },
        "email": "richard@piedpiper.com",
        "phone": {
          "countryCode": "1",
          "number": "5555555555"
        }
      },
      "officer": {
        "fullName": {
          "first": "Richard",
          "last": "Hendricks"
        },
        "dateOfBirth": "2001-08-10",
        "title": "CEO",
        "ssn": "721074426",
        "email": "richard@piedpiper.com",
        "phone": {
          "countryCode": "1",
          "number": "5555555555"
        },
        "address": {
          "street": "5230 Newell Rd",
          "city": "Palo Alto",
          "state": "CA",
          "postalCode": "94303",
          "country": "US"
        }
      },
      "beneficialOwners": [
        {
          "fullName": {
            "first": "Richard",
            "last": "Hendricks"
          },
          "dateOfBirth": "2001-08-10",
          "ssn": "123456789",
          "email": "richard@piedpiper.com",
          "percentage": 75,
          "phone": {
            "countryCode": "1",
            "number": "5555555555"
          },
          "address": {
            "street": "5230 Newell Rd",
            "city": "Palo Alto",
            "state": "CA",
            "postalCode": "94303",
            "country": "US"
          }
        }
      ],
      "tags": {
        "userId": "2ab1f266-04b9-41fb-b728-cd1962bca52c"
      },
      "idempotencyKey": "3a1a33be-4e12-4603-9ed0-820922389fb8"
    }
  }
}'
Verb POST
Url https://api.s.unit.sh/applications
Required Scope applications-write
Data Type businessApplication

Attributes

Name Type Description
name string Name of the business.
dba string Optional. “Doing business as”.
address Address Address of the business.
phone Phone Phone number of the business.
stateOfIncorporation string Two letters representing a US state.
ein string Business EIN (numbers only).
entityType string One of "Corporation", "LLC" or "Partnership".
ip string IP address of the end-customer creating the application.
website string Business's website. Optional.
contact BusinessContact Primary contact of the business.
officer Officer Officer representing the business (must be the CEO, COO, CFO, President or BenefitsAdministrationOfficer). To onboard a business successfully, you must provide the officer's full personal details as well as identifying documents.
beneficialOwners Array of BeneficialOwner Array of beneficial owners in the business. Beneficial owners are all people that, directly or indirectly, own 25% or more of the business. To onboard a business successfully, you must provide each beneficial owner's full personal details as well as identifying documents.
tags object See Tags. Tags that will be copied to the customer that this application creates (see Tag Inheritance).
idempotencyKey string See Idempotency.

Response

Response is a JSON:API document.

201 Created

Field Type Description
data BusinessApplication The newly created resource.
included Array of ApplicationDocument Resource Required documents for this application. Each document resource includes the document status.

Example Response:

{
  "data": {
    "type": "businessApplication",
    "id": "50",
    "attributes": {
      "createdAt": "2020-01-13T16:01:19.346Z",
      "name": "Pied Piper",
      "dba": null,
      "address": {
        "street": "5230 Newell Rd",
        "street2": null,
        "city": "Palo Alto",
        "state": "CA",
        "postalCode": "94303",
        "country": "US"
      },
      "phone": {
        "countryCode": "1",
        "number": "5555555555"
      },
      "stateOfIncorporation": "DE",
      "ein": "123456789",
      "entityType": "Corporation",
      "contact": {
        "fullName": {
          "first": "Richard",
          "last": "Hendricks"
        },
        "email": "richard@piedpiper.com",
        "phone": {
          "countryCode": "1",
          "number": "5555555555"
        }
      },
      "officer": {
        "fullName": {
          "first": "Richard",
          "last": "Hendricks"
        },
        "ssn": "123456789",
        "address": {
          "street": "5230 Newell Rd",
          "street2": null,
          "city": "Palo Alto",
          "state": "CA",
          "postalCode": "94303",
          "country": "US"
        },
        "dateOfBirth": "2001-08-10",
        "title": "CEO",
        "email": "richard@piedpiper.com",
        "phone": {
          "countryCode": "1",
          "number": "5555555555"
        },
        "status": "Approved"
      },
      "beneficialOwners": [
        {
          "fullName": {
            "first": "Richard",
            "last": "Hendricks"
          },
          "ssn": "123456789",
          "address": {
            "street": "5230 Newell Rd",
            "street2": null,
            "city": "Palo Alto",
            "state": "CA",
            "postalCode": "94303",
            "country": "US"
          },
          "dateOfBirth": "2001-08-10",
          "phone": {
            "countryCode": "1",
            "number": "5555555555"
          },
          "email": "richard@piedpiper.com",
          "percentage": 75,
          "status": "Approved"
        }
      ],
      "tags": {
        "userId": "2ab1f266-04b9-41fb-b728-cd1962bca52c"
      },
      "status": "AwaitingDocuments",
      "evaluationOutcome": "Approved"
    },
    "relationships": {
      "org": {
        "data": {
          "type": "org",
          "id": "1"
        }
      },
      "documents": {
        "data": [
          {
            "type": "document",
            "id": "1"
          },
          {
            "type": "document",
            "id": "2"
          },
          {
            "type": "document",
            "id": "3"
          }
        ]
      }
    }
  },
  "included": [
    {
      "type": "document",
      "id": "1",
      "attributes": {
        "documentType": "CertificateOfIncorporation",
        "status": "Required",
        "name": "Pied Piper",
        "description": "For Corporation: Please provide a certified copy of the Articles of Incorporation or Certificate of Incorporation..."
      }
    },
    {
      "type": "document",
      "id": "2",
      "attributes": {
        "documentType": "AddressVerification",
        "status": "Required",
        "name": "Richard Hendricks",
        "description": "Please provide a document to verify your address. Document may be a utility bill, bank statement, lease agreement or current pay stub.",
        "address": {
          "street": "5230 Newell Rd",
          "street2": null,
          "city": "Palo Alto",
          "state": "CA",
          "postalCode": "94303",
          "country": "US"
        }
      }
    },
    {
      "type": "document",
      "id": "3",
      "attributes": {
        "documentType": "IdDocument",        
        "status": "Required",
        "name": "Richard Hendricks",
        "description": "Please provide a copy of your unexpired government issued photo ID which would include Drivers License or State ID."
      }
    }
  ]
}

Get by Id

Get an application resource by id.

curl -X GET 'https://api.s.unit.sh/applications/43' \
-H "Authorization: Bearer ${TOKEN}"
Verb GET
Url https://api.s.unit.sh/applications/{id}
Required Scope applications

Response

Response is a JSON:API document.

200 OK

Field Type Description
data IndividualApplication or BusinessApplication Application resource. Can be either business or individual, as indicated by the type field.
included Array of ApplicationDocument Resource Application required documents, each document object also include the document status.

List

List application resources. Paging can be applied.

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

Query Parameters

Name Type Default Description
page[limit] integer 100 Maximum number of resources that will be returned. Maximum is 1000 resources. See Pagination.
page[offset] integer 0 Number of resources to skip. See Pagination.
filter[query] string (empty) Optional. Search term according to the Full-Text Search Rules.
filter[email] string (empty) Optional. Filter applications by email address (case sensitive).
filter[tags] Tags (JSON) (empty) Optional. Filter Applications by Tags.
sort string sort=-createdAt Optional. sort=createdAt for ascending order or sort=-createdAt (leading minus sign) for descending order.

Response

Example Response:

{
  "data": [
    {
      "type": "individualApplication",
      "id": "1",
      "attributes": {
        "createdAt": "2020-01-15T13:47:36.098Z",
        "fullName": {
          "first": "Peter",
          "last": "Parker"
        },
        "ssn": "721074426",
        "address": {
          "street": "20 Ingram St",
          "street2": null,
          "city": "Forest Hills",
          "state": "NY",
          "postalCode": "11375",
          "country": "US"
        },
        "dateOfBirth": "2001-08-10",
        "email": "peter@oscorp.com",
        "phone": {
          "countryCode": "1",
          "number": "5555555555"
        },
        "status": "AwaitingDocuments",
        "message": "Waiting for you to upload the required documents.",
        "evaluationOutcome": "Approved"
      },
      "relationships": {
        "org": {
          "data": {
            "type": "org",
            "id": "1"
          }
        },
        "documents": {
          "data": [
            {
              "type": "document",
              "id": "1"
            },
            {
              "type": "document",
              "id": "2"
            }
          ]
        }
      }
    },
    {
      "type": "businessApplication",
      "id": "2",
      "attributes": {
        "createdAt": "2020-01-15T13:48:38.527Z",
        "name": "Pied Piper",
        "dba": null,
        "address": {
          "street": "5230 Newell Rd",
          "street2": null,
          "city": "Palo Alto",
          "state": "CA",
          "postalCode": "94303",
          "country": "US"
        },
        "phone": {
          "countryCode": "1",
          "number": "5555555555"
        },
        "stateOfIncorporation": "DE",
        "ein": "123456789",
        "entityType": "Corporation",
        "contact": {
          "fullName": {
            "first": "Richard",
            "last": "Hendricks"
          },
          "email": "richard@piedpiper.com",
          "phone": {
            "countryCode": "1",
            "number": "5555555555"
          }
        },
        "officer": {
          "fullName": {
            "first": "Richard",
            "last": "Hendricks"
          },
          "ssn": "123456789",
          "address": {
            "street": "5230 Newell Rd",
            "street2": null,
            "city": "Palo Alto",
            "state": "CA",
            "postalCode": "94303",
            "country": "US"
          },
          "dateOfBirth": "2001-08-10",
          "email": "richard@piedpiper.com",
          "phone": {
            "countryCode": "1",
            "number": "5555555555"
          },
          "status": "Approved"
        },
        "beneficialOwners": [
          {
            "fullName": {
              "first": "Richard",
              "last": "Hendricks"
            },
            "ssn": "123456789",
            "address": {
              "street": "5230 Newell Rd",
              "street2": null,
              "city": "Palo Alto",
              "state": "CA",
              "postalCode": "94303",
              "country": "US"
            },
            "dateOfBirth": "2001-08-10",
            "phone": {
              "countryCode": "1",
              "number": "5555555555"
            },
            "email": "richard@piedpiper.com",
            "status": "Approved"
          }
        ],
        "status": "AwaitingDocuments",
        "message": "Waiting for you to upload the required documents.",
        "evaluationOutcome": "Approved"
      },
      "relationships": {
        "org": {
          "data": {
            "type": "org",
            "id": "1"
          }
        },
        "documents": {
          "data": [
            {
              "type": "document",
              "id": "1"
            },
            {
              "type": "document",
              "id": "2"
            },
            {
              "type": "document",
              "id": "3"
            }
          ]
        }
      }
    }
  ]
}

Response is a JSON:API document.

200 OK

Field Type Description
data Array of IndividualApplication or BusinessApplication Array of application resources. Each resource can be either business or individual, as indicated by the type field.

Application Document

Application document resources represent the documents that need to be collected for the application to be evaluated. Their initial status is always Required. The documents will be different in the case of individual and business applications.

Application document resources are created automatically once an application is created.

Application Document Status

Status Description
Required The document is required for the application to be evaluated.
ReceivedBack Back-side of the document was received. Front-side is still required. Only relevant for IdDocument document type.
ReceivedFront Front-side of the document was received. Back-side is still required. Only relevant for IdDocument document type.
Invalid The document is invalid. You may re-upload the correct document for the application to be evaluated.
Approved The document is approved.
PendingReview The document is currently undergoing review.

Document Types

Name Description
IdDocument An individual's Drivers License or State ID. Both front-side and back-side are required.
Passport An individual's passport.
AddressVerification An individual's document to verify address. Document may be a utility bill, bank statement, lease agreement or current pay stub.
SocialSecurityCard An individual's social security card.
CertificateOfIncorporation A business's certificate of incorporation.
EmployerIdentificationNumberConfirmation A business's EIN confirmation document (either IRS form 147c or IRS form CP-575).

Upload Document

Uploads a document file. Supported file types are pdf, jpeg or png.

curl --request PUT 'https://api.s.unit.sh/applications/46/documents/3' \
--header 'Content-Type: application/pdf' \
--data-binary 'passport.pdf'
Verb PUT
Url https://api.s.unit.sh/applications/{applicationId}/documents/{documentId}
Required Scope applications-write

Headers

Header Value
Content-Type One of image/png, image/jpeg, or application/pdf.

Response

Example Response:

{
    "data": {
        "type": "document",
        "id": "3",
        "attributes": {
            "documentType": "Passport",
            "status": "Approved",
            "description": "Please provide a current copy of your passport.",
            "name": "Richard Hendricks",
            "dateOfBirth": "2001-08-15"
        }
    }
}

Response is a JSON:API document.

200 OK

Field Type Description
data ApplicationDocument The target resource after the operation was completed.

Upload Document Back-Side

Uploads the back-side of a document. Supported file types are pdf, jpeg or png.

curl --request PUT 'https://api.s.unit.sh/applications/46/documents/3/back' \
--header 'Content-Type: application/pdf' \
--data-binary 'driver-license-back.pdf'
Verb PUT
Url https://api.s.unit.sh/applications/{applicationId}/documents/{documentId}/back
Required Scope applications-write

Headers

Header Value
Content-Type One of image/png, image/jpeg, or application/pdf.

Response

Example Response:

{
    "data": {
        "type": "document",
        "id": "3",
        "attributes": {
            "documentType": "IdDocument",
            "status": "Approved",
            "description": "Please provide a copy of your unexpired government issued photo ID which would include Drivers License or State ID.",
            "name": "Richard Hendricks",
            "dateOfBirth": "2001-08-15"
        }
    }
}

Response is a JSON:API document.

200 OK

Field Type Description
data ApplicationDocument The target resource after the operation was completed.

List

List application documents.

curl -X GET 'https://api.s.unit.sh/applications/1/documents' \
-H "Authorization: Bearer ${TOKEN}"
Verb GET
Url https://api.s.unit.sh/applications/{applicationId}/documents
Required Scope applications

Response

Example Response:

{
  "data": [
    {
      "type": "document",
      "id": "1",
      "attributes": {
        "documentType": "CertificateOfIncorporation",
        "status": "Required",
        "description": "Please provide a certified copy of the Articles of Incorporation or Certificate of Incorporation.",
        "name": "Pied Piper"
      }
    },
    {
      "type": "document",
      "id": "2",
      "attributes": {
        "documentType": "AddressVerification",
        "status": "Required",
        "description": "Please provide a document to verify your address. Document may be a utility bill, bank statement, lease agreement or current pay stub.",
        "name": "Richard Hendricks",
        "address": {
          "street": "5230 Newell Rd",
          "street2": null,
          "city": "Palo Alto",
          "state": "CA",
          "postalCode": "94303",
          "country": "US"
        }
      }
    },
    {
      "type": "document",
      "id": "3",
      "attributes": {
        "documentType": "IdDocument",
        "status": "Required",
        "description": "Please provide a copy of your unexpired government issued photo ID which would include Drivers License or State ID.",
        "name": "Richard Hendricks"
      }
    }
  ]
}

Response is a JSON:API document.

200 OK

Field Type Description
data Array of ApplicationDocument Resource Array of application documents.

Customers

Customers represent individuals or businesses that you may create financial products for.

You cannot create customer resources directly — they are automatically created once an application is approved.

A customer can be either BusinessCustomer or IndividualCustomer.

Update Individual Customer

Update an IndividualCustomer.

Update an individual customer:

curl -X PATCH 'https://api.s.unit.sh/customers/:customerId' \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: Bearer ${TOKEN}' \
--data-raw '{
  "data":{
    "type": "individualCustomer",
    "attributes": {
      "address": {
        "street": "5231 Newell Rd",
        "street2": null,
        "city": "Palo Alto",
        "state": "CA",
        "postalCode": "94301",
        "country": "US"
      },
      "email": "richard@piedpiper.com",
      "phone": {
        "countryCode": "1",
        "number": "5555555555"
      }
    }
  }
}'
Verb PATCH
Url https://api.s.unit.sh/customers/:customerId
Required Scope customers-write
Data Type customer-tags-write

Attributes

Name Type Description
address Address Address of the individual.
To modify or add specify the new address.
phone Phone Phone of the individual.
To modify or add specify the new phone number.
email string Email address of the individual.
To modify or add specify the new email address.
dba string If the individual is a sole proprietor who is doing business under a different name.
To modify or add specify the new dba name.
tags object See Updating Tags.

Response

Response is a JSON:API document.

200 OK

Field Type Description
data IndividualCustomer Customer resource.

Update Business Customer

Update an BusinessCustomer.

Update business customer:

curl -X PATCH 'https://api.s.unit.sh/customers/:customerId' \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: Bearer ${TOKEN}' \
--data-raw '{
  "data":{
    "type": "businessCustomer",
    "attributes": {
      "address": {
        "street": "5231 Newell Rd",
        "street2": null,
        "city": "Palo Alto",
        "state": "CA",
        "postalCode": "94301",
        "country": "US"
      },
      "phone": {
        "countryCode": "1",
        "number": "5555555555"
      },
      "contact": {
        "fullName": {
          "first": "Jone",
          "last": "Doe"
        },
        "email": "jone.doe@unit-finance.com",
        "phone": {
          "countryCode": "1",
          "number": "2025550108"
        }
      }
    }
  }
}'
Verb PATCH
Url https://api.s.unit.sh/customers/:customerId
Required Scope customers-write
Data Type customer-tags-write

Attributes

Name Type Description
address Address Address of the business.
To modify specify the new address.
phone Phone Phone of the business.
To modify specify the new phone number.
contact BusinessContact Primary contact of the business.
tags object See Updating Tags.

Response

Response is a JSON:API document.

200 OK

Field Type Description
data BusinessCustomer Customer resource.

Get by Id

Get a customer resource by id.

curl -X GET 'https://api.s.unit.sh/customers/8' \
-H "Authorization: Bearer ${TOKEN}"
Verb GET
Url https://api.s.unit.sh/customers/{id}
Required Scope customers

Response

Response is a JSON:API document.

200 OK

Field Type Description
data BusinessCustomer or IndividualCustomer Customer resource. Can be either business or individual, as indicated by the type field.

List

List customer resources. Paging can be applied.

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

Query Parameters

Name Type Default Description
page[limit] integer 100 Maximum number of resources that will be returned. Maximum is 1000 resources. See Pagination.
page[offset] integer 0 Number of resources to skip. See Pagination.
filter[query] string (empty) Optional. Search term according to the Full-Text Search Rules.
filter[email] string (empty) Optional. Filter customers by email address (case sensitive).
filter[tags] Tags (JSON) (empty) Optional. Filter Customers by Tags.
sort string sort=-createdAt Optional. sort=createdAt for ascending order or sort=-createdAt (leading minus sign) for descending order.

Response

Example Response:

{
  "data": [
    {
      "type": "businessCustomer",
      "id": "1",
      "attributes": {
        "createdAt": "2020-05-10T12:28:37.698Z",
        "name": "Pied Piper",
        "address": {
          "street": "5230 Newell Rd",
          "street2": null,
          "city": "Palo Alto",
          "state": "CA",
          "postalCode": "94303",
          "country": "US"
        },
        "phone": {
          "countryCode": "1",
          "number": "1555555566"
        },
        "stateOfIncorporation": "DE",
        "ein": "123456789",
        "entityType": "Corporation",
        "contact": {
          "fullName": {
            "first": "Richard",
            "last": "Hendricks"
          },
          "email": "richard@piedpiper.com",
          "phone": {
            "countryCode": "1",
            "number": "1555555566"
          }
        },
        "riskRate": "low"
      },
      "relationships": {
        "org": {
          "data": {
            "type": "org",
            "id": "1"
          }
        },
        "application": {
          "data": {
            "type": "businessApplication",
            "id": "1"
          }
        }
      }
    },
    {
      "type": "individualCustomer",
      "id": "8",
      "attributes": {
        "createdAt": "2020-05-12T19:41:04.123Z",
        "fullName": {
          "first": "Peter",
          "last": "Parker"
        },
        "ssn": "721074426",
        "address": {
          "street": "20 Ingram St",
          "street2": null,
          "city": "Forest Hills",
          "state": "NY",
          "postalCode": "11375",
          "country": "US"
        },
        "dateOfBirth": "2001-08-10",
        "email": "peter@oscorp.com",
        "phone": {
          "countryCode": "1",
          "number": "1555555566"
        },
        "riskRate": "low"
      },
      "relationships": {
        "org": {
          "data": {
            "type": "org",
            "id": "1"
          }
        },
        "application": {
          "data": {
            "type": "individualApplication",
            "id": "8"
          }
        }
      }
    }
  ]
}

Response is a JSON:API document.

200 OK

Field Type Description
data Array of BusinessCustomer or IndividualCustomer Array of customer resources. Each resource can be either business or individual, as indicated by the type field.

Deposit Accounts

Create Deposit Account

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"
        }
      }
    }
  }
}'

Creates a deposit account for a Customer using a specified deposit product. A deposit product is a predefined set of terms associated with this deposit account (e.g. interest rate).

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

Verb POST
Url https://api.s.unit.sh/accounts
Required Scope accounts-write
Data Type depositAccount

Attributes

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

Relationships

Name Type Description
customer JSON:API Relationship The customer the deposit account belongs to. The customer is either a business or an individual customer.

Response

Response is a JSON:API document.

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

201 Created

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

Close Account

Closes an account.

curl -X POST 'https://api.s.unit.sh/accounts/10000/close' \
-H "Authorization: Bearer ${TOKEN}"
Verb POST
Url https://api.s.unit.sh/accounts/:accountId/close
Required Scope accounts-write

Response

Response is a JSON:API document.

200 OK

Field Type Description
data DepositAccount Deposit Account resource.

Reopen Account

Reopen an account.

curl -X POST 'https://api.s.unit.sh/accounts/10000/reopen' \
-H "Authorization: Bearer ${TOKEN}"
Verb POST
Url https://api.s.unit.sh/accounts/:accountId/reopen
Required Scope accounts-write

Response

Response is a JSON:API document.

200 OK

Field Type Description
data DepositAccount Deposit Account resource.

Get by Id

Get a deposit account resource by id.

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

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.

List

List deposit account resources. Paging can be applied.

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

Query Parameters

Name Type Default Description
page[limit] integer 100 Maximum number of resources that will be returned. Maximum is 1000 resources. See Pagination.
page[offset] integer 0 Number of resources to skip. See Pagination.
filter[customerId] string (empty) Optional. Filters the results by the specified customer id.
filter[tags] Tags (JSON) (empty) Optional. Filter Accounts by Tags.
include string (empty) Optional. Related resource available to include: customer. See Getting Related Resources

Response

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"
          }
        }
      }
    }
  ]
}

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.

Update

Example Request:

Update a deposit account.

{
  "data": {
    "type": "depositAccount",
    "attributes": {
      "tags": {
        "purpose": "Tax",
        "trackUserId": null,
        "newTag": "New tag value"
      }
    }
  }
}
Verb PATCH
Url https://api.s.unit.sh/accounts/:accountId
Required Scope depositAccount

Attributes

Name Type Description
tags object See Updating Tags.

Response

Response is a JSON:API document.

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

200 OK

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

Limits

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

Example Response

{
    "data": {
        "type": "limits",
        "attributes": {
            "ach": {
                "limits": {
                    "dailyDebit": 50000,
                    "dailyCredit": 50000,
                    "monthlyDebit": 2000000,
                    "monthlyCredit": 2000000
                },
                "totalsDaily": {
                    "debits": 25000,
                    "credits": 10000
                },
                "totalsMonthly": {
                    "debits": 800300,
                    "credits": 250000
                }
            }
        }
    }
}

Monetary transactions (such as originating ACH payments, ATM withdrawals or deposits) are subjected to daily and monthly amount limits. Once the limit is reached, the transaction might be rejected. The limits are determined by us and are set in the terms configured in your account’s deposit product. You may contact Unit to change the limits for an account or a group of accounts.

The daily limits are reset at 7:00 p.m. EST. The monthly limits are reset on the first of each month. We provide an API to query the current limits (and daily/monthly totals) for your account.

Fees

Fees allow you to charge the customer custom fees according to your business rules, like monthly subscriptions. The fees will be paid to your Revenue Account and will show up on the customer monthly statements.

Create Fee

Example Request:

curl -X POST 'https://api.s.unit.sh/fees' \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: Bearer ${TOKEN}' \
--data-raw '{
  "data": {
    "type": "fee",
    "attributes": {
      "amount": 1000,
      "description": "Monthly Subscription"
    },
    "relationships": {
      "account": {
        "data": {
          "type": "depositAccount",
          "id": "10097"
        }
      }
    }
  }
}'

Creates a fee for an Account.

Verb POST
Url https://api.s.unit.sh/fees
Required Scope accounts-write
Data Type fee

Attributes

Name Type Description
amount integer The amount (in cents) to charge the account.
description string Description of the fee (maximum of 50 characters).
tags object See Tags.
idempotencyKey string See Idempotency.

Relationships

Name Type Description
account JSON:API Relationship The account to charge the fee.

Response

Response is a JSON:API document.

Example Response:

{
  "data": {
    "type": "fee",
    "id": "1234",
    "attributes": {
      "amount": 1000,
      "description": "Monthly Subscription"
    },
    "relationships": {
      "account": {
        "data": {
          "type": "depositAccount",
          "id": "10097"
        }
      }
    }
  }
}

201 Created

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

Payments

Unit allows you to originate and receive ACH payments from/to all deposit accounts. For general information on the ACH network, we recommend the following series from Gusto: How ACH Works: a Developer's Perspective.

ACH Origination overview

In Unit, an ACH payment originates from a Deposit Account. The entity on the other side of the payment is called a Counterparty. A counterparty is a combination of routing number, account number, account type, and name.

Each ACH payment has a direction- either Debit or Credit. In the context of ACH payment origination, the directions work as follows:

ACH returns are handled by Unit:

Originating an ACH payment supports Idempotency, to ensure that multiple identical requests will have the same effect as a single request.

ACH payment to inline Counterparty

Example Request:

curl -X POST 'https://api.s.unit.sh/payments' \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: Bearer ${TOKEN}' \
--data-raw '{
  "data": {
    "type": "achPayment",
      "attributes": {
        "amount": 10000,
        "direction": "Credit",
        "counterparty": {
          "routingNumber": "812345678",
          "accountNumber": "12345569",
          "accountType": "Checking",
          "name": "Jane Doe"
        },
        "description": "Funding"
      },
      "relationships": {
        "account": {
          "data": {
            "type": "depositAccount",
            "id": "555"
          }
      }
    }
  }
}'

Originates an ACH payment to a counterparty which is specified inline (vs to a linked Counterparty Resource).

Verb POST
Url https://api.s.unit.sh/payments
Required Scope payments-write or payments-write-ach-debit
Data Type achPayment

Attributes

Name Type Description
amount integer The amount (in cents).
direction string The direction in which the funds flow.
counterparty Counterparty The party on the other side of the ACH payment.
description string Payment description (maximum of 10 characters), also known as Company Entry Description, this will show up on statement of the counterparty.
addenda string Optional, additional payment description (maximum of 50 characters), not all institutions present that.
idempotencyKey string See Idempotency.
tags object See Tags. Tags that will be copied to any transaction that this payment creates (see Tag Inheritance).

Relationships

Name Type Description
account JSON:API Relationship The Deposit Account originating the payment.

Response

Example Response:

{
  "data": {
    "type": "achPayment",
    "id": "50",
    "attributes": {
      "createdAt": "2020-01-13T16:01:19.346Z",
      "status": "Pending",
      "reason": null,
      "counterparty": {
        "routingNumber": "812345678",
        "accountNumber": "12345569",
        "accountType": "Checking",
        "name": "Jane Doe"
      },
      "description": "Funding",
      "direction": "Credit",
      "amount": 10000,
      "tags" : {
        "purpose": "internal"
      }
    },
    "relationships": {
      "account": {
        "data": {
          "type": "depositAccount",
          "id": "555"
        }
      },
      "customer": {
        "data": {
          "type": "individualCustomer",
          "id": "99823"
        }
      }
    }
  }
}

Response is a JSON:API document.

ACH payment to linked Counterparty

Example Request:

curl -X POST 'https://api.s.unit.sh/payments' \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: Bearer ${TOKEN}' \
--data-raw '{
  "data": {
    "type": "achPayment",
    "attributes": {
      "amount": 10000,
      "direction": "Credit",
      "description": "Funding"
    },
    "relationships": {
      "account": {
        "data": {
          "type": "depositAccount",
          "id": "555"
        }
      },
      "counterparty": {
        "data": {
          "type": "counterparty",
          "id": "4567"
        }
      }
    }
  }
}'

Originates an ACH payment to a Counterparty. The counterparty should be created separately through Create Counterparty.

Verb POST
Url https://api.s.unit.sh/payments
Required Scope payments-write-counterparty or payments-write
Data Type achPayment

Attributes

Name Type Description
amount integer The amount (in cents).
direction string The direction in which the funds flow.
description string Payment description (maximum of 10 characters), also known as Company Entry Description, this will show up on statement of the counterparty.
addenda string Optional, additional payment description (maximum of 50 characters), not all institutions present that.
idempotencyKey string See Idempotency.
tags object See Tags. Tags that will be copied to any transaction that this payment creates (see Tag Inheritance).

Relationships

Name Type Description
account JSON:API Relationship The Deposit Account originating the payment.
counterparty JSON:API Relationship The Counterparty the payment to be made to.

Response

Example Response:

{
  "data": {
    "type": "achPayment",
    "id": "50",
    "attributes": {
      "createdAt": "2020-01-13T16:01:19.346Z",
      "status": "Pending",
      "reason": null,
      "counterparty": {
        "routingNumber": "812345678",
        "accountNumber": "12345569",
        "accountType": "Checking",
        "name": "Jane Doe"
      },
      "description": "Funding",
      "direction": "Credit",
      "amount": 10000,
      "tags" : {
        "purpose": "internal"
      }
    },
    "relationships": {
      "account": {
        "data": {
          "type": "depositAccount",
          "id": "555"
        }
      },
      "customer": {
        "data": {
          "type": "individualCustomer",
          "id": "99823"
        }
      },
      "counterparty": {
        "data": {
          "type": "counterparty",
          "id": "4567"
        }
      }
    }
  }
}

Response is a JSON:API document.

ACH payment with Plaid token

Example Request:

curl -X POST 'https://api.s.unit.sh/payments' \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: Bearer ${TOKEN}' \
--data-raw '{
  "data": {
    "type": "achPayment",
    "attributes": {
      "amount": 10000,
      "direction": "Debit",
      "plaidProcessorToken": "processor-5a62q307-ww0a-6737-f6db-pole26004556",
      "description": "Funding"
    },
    "relationships": {
      "account": {
        "data": {
          "type": "depositAccount",
          "id": "555"
        }
      }
    }
  }
} '

Originates an ACH payment to a counterparty which is verified by Plaid.

Verb POST
Url https://api.s.unit.sh/payments
Required Scope payments-write or payments-write-ach-debit
Data Type achPayment

Attributes

Name Type Description
amount integer The amount (in cents)
direction string The direction in which the funds flow
description string Payment description (maximum of 50 characters)
idempotencyKey string See idempotency
counterpartyName string Name of the person or company that owns the counterparty bank account.
plaidProcessorToken string See Create Plaid processor token API

Relationships

Name Type Description
account JSON:API Relationship The Deposit Account originating the payment

Response

Example Response:

{
  "data": {
    "type": "achPayment",
    "id": "50",
    "attributes": {
      "createdAt": "2020-01-13T16:01:19.346Z",
      "status": "Pending",
      "reason": null,
      "counterparty": {
        "routingNumber": "812345678",
        "accountNumber": "12345569",
        "accountType": "Checking",
        "name": "Jane Doe"
      },
      "description": "Funding",
      "direction": "Credit",
      "amount": 10000,
      "tags" : {
        "purpose": "internal"
      }
    },
    "relationships": {
      "account": {
        "data": {
          "type": "depositAccount",
          "id": "555"
        }
      },
      "customer": {
        "data": {
          "type": "individualCustomer",
          "id": "99823"
        }
      }
    }
  }
}

Response is a JSON:API document.

Receiving an ACH payment

You can receive ACH payments (both Debit and Credit) into any deposit account. To do so, you may provide the routing number and account number to trusted third parties. These numbers are both attributes of any deposit account.

Received ACH payments are processed automatically. You can get notified on them by listening to the transaction.created webhook and inspecting the payload for a received ACH transaction.

Examples:

ACH Status

The ACH network operates in batches. When you originate an ACH payment, it will be created with a Pending status. You may track its progress using the status attribute or listening to relevant webhooks, such as payment.sent or payment.returned.

The possible status values are:

Status Description
Pending The payment was created on the Unit ledger but was not yet delivered to the ACH network. Payments with Pending status may be canceled by the originator.
Rejected The payment was rejected due to insufficient funds or exceeding daily ACH limits (see reason for more details).
Clearing (Debit only) The payment was sent but the deposit account was not credited yet.
Sent The payment was processed by the ACH network. This is the final state for successful payments.
Canceled The payment was canceled.
Returned The payment was processed but the network or the receiving bank returned the payment (see reason for more details).

Create a Book payment

Example Request:

curl -X POST 'https://api.s.unit.sh/payments' \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: Bearer ${TOKEN}' \
--data-raw '{
  "data": {
    "type": "bookPayment",
    "attributes": {
      "amount": 10000,
      "description": "Funding"
    },
    "relationships": {
      "account": {
        "data": {
          "type": "depositAccount",
          "id": "555"
        }
      },
      "counterpartyAccount": {
        "data": {
          "type": "depositAccount",
          "id": "99821"
        }
      }
    }
  }
}'

Book payments are free and instant fund transfers between two accounts under your organization. Common uses for book payments include:

Once you create a book payment, Unit will process it instantly and free of charge. The result will be one Book Transaction in each account.

Verb POST
Url https://api.s.unit.sh/payments
Required Scope payments-write
Data Type bookPayment

Attributes

Name Type Description
amount integer The amount (in cents).
description string Payment description (maximum of 50 characters), this will show up on statement of the counterparty.
idempotencyKey string See Idempotency.
tags object See Tags. Tags that will be copied to any transaction that this payment creates (see Tag Inheritance).

Relationships

Name Type Description
account JSON:API Relationship The Deposit Account originating the payment.
counterpartyAccount JSON:API Relationship The Counterparty account the payment to be made to.

Response

Example Response:

{
  "data": {
    "type": "bookPayment",
    "id": "1232",
    "attributes": {
      "createdAt": "2021-02-21T13:03:19.025Z",
      "amount": 1500,
      "direction": "Credit",
      "description": "Funding",
      "status": "Sent"
    },
    "relationships": {
      "account": {
        "data": {
          "type": "account",
          "id": "555"
        }
      },
      "customer": {
        "data": {
          "type": "customer",
          "id": "10000"
        }
      },
      "counterpartyAccount": {
        "data": {
          "type": "account",
          "id": "99821"
        }
      },
      "counterpartyCustomer": {
        "data": {
          "type": "customer",
          "id": "10000"
        }
      },
      "transaction": {
        "data": {
          "type": "transaction",
          "id": "1413"
        }
      }
    }
  }
}

Response is a JSON:API document.

Update ACH Payment

Update an ACH Payment.

Update an ACH payment:

curl -X PATCH 'https://api.s.unit.sh/payments/:paymentId' \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: Bearer ${TOKEN}' \
--data-raw '{
  "data":{
    "type": "achPayment",
    "attributes": {
      "tags": {
        "by": null,
        "uuid": "83033b64-38f8-4dbc-91a1-313ff0156d02"
      }
    }
  }
}'
Verb PATCH
Url https://api.s.unit.sh/payments/:paymentId
Required Scope payments-write

Attributes

Name Type Description
tags object See Updating Tags.

Response

Response is a JSON:API document.

200 OK

Field Type Description
data AchPayment The updated ACH payment resource.

Update Book Payment

Update a Book Payment.

Update book payment:

curl -X PATCH 'https://api.s.unit.sh/payments/:paymentId' \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: Bearer ${TOKEN}' \
--data-raw '{
  "data":{
    "type": "bookPayment",
    "attributes": {
      "tags": {
        "by": null,
        "uuid": "83033b64-38f8-4dbc-91a1-313ff0156d02"
      }
    }
  }
}'
Verb PATCH
Url https://api.s.unit.sh/payments/:paymentId
Required Scope payments-write

Attributes

Name Type Description
tags object See Updating Tags.

Response

Response is a JSON:API document.

200 OK

Field Type Description
data BookPayment The updated Book payment resource.

Receiving a wire payment

You can receive wire (Fedwire) payments into any deposit account. To do so, you may provide the routing number and account number to trusted third parties. These numbers are both attributes of any Deposit Account.

Received wire payments are processed automatically. You can get notified on them by listening to the transaction.created webhook and inspecting the payload for a Wire Transaction.

As an example, receiving a wire payment in the amount of $4,000 when the balance is $0 will automatically result in a balance increase. Two transactions will be created: one Wire Transaction and one associated Fee Transaction (if the fee is non-zero).

Get by Id

Get a payment by id.

curl -X GET 'https://api.s.unit.sh/payments/100' \
-H "Authorization: Bearer ${TOKEN}"
Verb GET
Url https://api.s.unit.sh/payments/{id}
Required Scope payments

Query Parameters

Name Type Default Description
include string (empty) Optional. A comma-separated list of related resources to include in the response. Related resources include: customer, account, transaction. See Getting Related Resources

Response

Response is a JSON:API document.

200 OK

Field Type Description
data ACH Payment Payment resource.
included Array of DepositAccount or Customer or Transaction Array of resources requested by the include query parameter.

List

List payments resources. Filtering, paging and sorting can be applied.

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

Query Parameters

Name Type Default Description
page[limit] integer 100 Maximum number of resources that will be returned. Maximum is 1000 resources. See Pagination.
page[offset] integer 0 Number of resources to skip. See Pagination.
filter[accountId] string (empty) Optional. Filters the results by the specified account id.
filter[customerId] string (empty) Optional. Filters the results by the specified customer id.
filter[tags] Tags (JSON) (empty) Optional. Filter Payments by Tags.
sort string sort=-createdAt Optional. Leave empty or provide sort=createdAt for ascending order. Provide sort=-createdAt (leading minus sign) for descending order.
include string (empty) Optional. A comma-separated list of related resources to include in the response. Related resources include: customer, account, transaction. See Getting Related Resources

Response

Example Response:

{
  "data": [
    {
      "type": "achPayment",
      "id": "50",
      "attributes": {
        "createdAt": "2020-01-13T16:01:19.346Z",
        "status": "Pending",
        "counterparty": {
          "routingNumber": "812345678",
          "accountNumber": "12345569",
          "accountType": "Checking",
          "name": "Jane Doe"
        },
        "description": "Funding",
        "direction": "Credit",
        "amount": 10000
      },
      "relationships": {
        "account": {
          "data": {
            "type": "depositAccount",
            "id": "555"
          }
        },
        "customer": {
          "data": {
            "type": "individualCustomer",
            "id": "99823"
          }
        },
        "counterparty": {
          "data": {
            "type": "counterparty",
            "id": "4567"
          }
        },
        "transaction": {
          "data": {
            "type": "transaction",
            "id" : "4003"
          }
        }
      }
    }
  ]
}

Response is a JSON:API document.

200 OK

Field Type Description
data Array of ACH Payment Array of payment resources.
included Array of DepositAccount or Customer or Transaction Array of resources requested by the include query parameter.

Cards

The card resource represents a debit card under an account.

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

Create Individual Debit Card

Creates and ships a physical debit card to an individual. You must link the card to an account using the account field under relationships object. The linked account must belong to an individual customer (and not a business).

Example Request:

curl -X POST 'https://api.s.unit.sh/cards' \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: Bearer ${TOKEN}' \
--data-raw '{
  "data":{
    "type":"individualDebitCard",
    "attributes": {
      "shippingAddress": {
        "street": "5230 Newell Rd",
        "street2": null,
        "city": "Palo Alto",
        "state": "CA",
        "postalCode": "94303",
        "country": "US"
      },
      "idempotencyKey": "3a1a33be-4e12-4603-9ed0-820922389fb8"
    },
    "relationships": {
      "account": {
        "data": {
          "type": "depositAccount",
          "id": "2"
        }
      }
    }
  }
}'
Verb POST
Url https://api.s.unit.sh/cards
Required Scope cards-write
Data Type individualDebitCard

Attributes

Name Type Description
shippingAddress Address Address to ship the card to. Optional, if not specified, the individual address is used.
design string Optional. You may omit if you only have one card design. Please contact Unit if you need multiple card designs.
idempotencyKey string See Idempotency.
tags object See Tags.

Relationships

Name Type Description
account JSON:API Relationship Link to the account the card belongs to. Holder of the account must be an individual.

Response

Response is a JSON:API document.

Example Response:

{
  "data": {
    "type": "individualDebitCard",
    "id": "8",
    "attributes": {
      "createdAt": "2020-05-13T09:07:47.645Z",
      "last4Digits": "1234",
      "expirationDate": "2022-05",
      "shippingAddress": {
        "street": "5230 Newell Rd",
        "street2": null,
        "city": "Palo Alto",
        "state": "CA",
        "postalCode": "94303",
        "country": "US"
      },
      "status": "Inactive"
    },
    "relationships": {
      "account": {
        "data": {
          "type": "depositAccount",
          "id": "2"
        }
      },
      "customer": {
        "data": {
          "type": "individualCustomer",
          "id": "2"
        }
      }
    }
  }
}

201 Created

Field Type Description
data IndividualDebitCard The target resource after the operation was completed.

Create Business Debit Card

Creates and ships a physical debit card to a business card holder. You must link the card to an account using the account field under relationships object. The linked account must belong to a business customer.

Example Request:

curl -X POST 'https://api.s.unit.sh/cards' \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: Bearer ${TOKEN}' \
--data-raw '{
  "data":{
    "type":"businessDebitCard",
    "attributes": {
      "shippingAddress": {
        "street": "5230 Newell Rd",
        "street2": null,
        "city": "Palo Alto",
        "state": "CA",
        "postalCode": "94303",
        "country": "US"
      },
      "fullName": {
        "first": "Richard",
        "last": "Hendricks"
      },
      "ssn": "123456789",
      "address": {
        "street": "5230 Newell Rd",
        "street2": null,
        "city": "Palo Alto",
        "state": "CA",
        "postalCode": "94303",
        "country": "US"
      },
      "dateOfBirth": "2001-08-10",
      "email": "richard@piedpiper.com",
      "phone": {
        "countryCode": "1",
        "number": "5555555555"
      },
      "idempotencyKey": "3a1a33be-4e12-4603-9ed0-820922389fb8"
    },
    "relationships": {
      "account": {
        "data": {
          "type": "depositAccount",
          "id": "1"
        }
      }
    }
  }
}'
Verb POST
Url https://api.s.unit.sh/cards
Required Scope cards-write
Data Type businessDebitCard

Attributes

Name Type Description
shippingAddress Address Address to ship the card to. Optional, if not specified, card holder address is used.
ssn string SSN of the card holder (numbers only). Either an SSN or a passport number is required.
passport string Passport number of the card holder. Either an SSN or a passport is required.
nationality ISO31661-Alpha2 string Required on passport only. Two letters representing the card holder nationality. (e.g. “US”).
fullName FullName Full name of the card holder.
dateOfBirth RFC3339 Date string Date of birth of the card holder (e.g. "2001-08-15").
address Address Address of the card holder.
phone Phone Phone of the card holder.
email string Email address of the card holder.
design string Optional. You may omit if you only have one card design. Please contact Unit if you need multiple card designs.
idempotencyKey string See Idempotency.
tags object See Tags.

Relationships

Name Type Description
account JSON:API Relationship The account the card belongs to. Holder of the account must be a business.

Response

Response is a JSON:API document.

Example Response:

{
  "data": {
    "type": "businessDebitCard",
    "id": "9",
    "attributes": {
      "createdAt": "2020-05-13T09:42:21.857Z",
      "last4Digits": "2074",
      "expirationDate": "2022-05",
      "shippingAddress": {
        "street": "5230 Newell Rd",
        "street2": null,
        "city": "Palo Alto",
        "state": "CA",
        "postalCode": "94303",
        "country": "US"
      },
      "address": {
        "street": "5230 Newell Rd",
        "street2": null,
        "city": "Palo Alto",
        "state": "CA",
        "postalCode": "94303",
        "country": "US"
      },
      "fullName": {
        "first": "Richard",
        "last": "Hendricks"
      },
      "phone": {
        "countryCode": "1",
        "number": "5555555666"
      },
      "email": "richard@piedpiper.com",
      "dateOfBirth": "2001-08-10",
      "ssn": "123456789",
      "status": "Inactive"
    },
    "relationships": {
      "account": {
        "data": {
          "type": "depositAccount",
          "id": "1"
        }
      },
      "customer": {
        "data": {
          "type": "businessCustomer",
          "id": "1"
        }
      }
    }
  }
}

201 Created

Field Type Description
data BusinessDebitCard The target resource after the operation was completed.

Create Individual Virtual Debit Card

Creates a debit card for an individual. You must link the card to an account using the account field under relationships object. The linked account must belong to an individual customer (and not a business).

Example Request:

curl -X POST 'https://api.s.unit.sh/cards' \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: Bearer ${TOKEN}' \
--data-raw '{
  "data":{
    "type":"individualVirtualDebitCard",
    "attributes": {
      "idempotencyKey": "3a1a33be-4e12-4603-9ed0-820922389fb8"
    },
    "relationships": {
      "account": {
        "data": {
          "type": "depositAccount",
          "id": "2"
        }
      }
    }
  }
}'
Verb POST
Url https://api.s.unit.sh/cards
Required Scope cards-write
Data Type individualVirtualDebitCard

Attributes

Name Type Description
idempotencyKey string See Idempotency.
tags object See Tags.

Relationships

Name Type Description
account JSON:API Relationship Link to the account the card belongs to. Holder of the account must be an individual.

Response

Response is a JSON:API document.

Example Response:

{
  "data": {
    "type": "individualVirtualDebitCard",
    "id": "8",
    "attributes": {
      "createdAt": "2020-05-13T09:07:47.645Z",
      "last4Digits": "1234",
      "expirationDate": "2022-05",
      "status": "Inactive"
    },
    "relationships": {
      "account": {
        "data": {
          "type": "depositAccount",
          "id": "2"
        }
      },
      "customer": {
        "data": {
          "type": "individualCustomer",
          "id": "2"
        }
      }
    }
  }
}

201 Created

Field Type Description
data IndividualVirtualDebitCard The target resource after the operation was completed.

Create Business Virtual Debit Card

Creates a debit card for a business. You must link the card to an account using the account field under relationships object. The linked account must belong to a business customer.

Example Request:

curl -X POST 'https://api.s.unit.sh/cards' \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: Bearer ${TOKEN}' \
--data-raw '{
  "data":{
    "type":"businessVirtualDebitCard",
    "attributes": {
      "fullName": {
        "first": "Richard",
        "last": "Hendricks"
      },
      "ssn": "123456789",
      "address": {
        "street": "5230 Newell Rd",
        "street2": null,
        "city": "Palo Alto",
        "state": "CA",
        "postalCode": "94303",
        "country": "US"
      },
      "dateOfBirth": "2001-08-10",
      "email": "richard@piedpiper.com",
      "phone": {
        "countryCode": "1",
        "number": "5555555555"
      },
      "idempotencyKey": "3a1a33be-4e12-4603-9ed0-820922389fb8"
    },
    "relationships": {
      "account": {
        "data": {
          "type": "depositAccount",
          "id": "1"
        }
      }
    }
  }
}'
Verb POST
Url https://api.s.unit.sh/cards
Required Scope cards-write
Data Type businessVirtualDebitCard

Attributes

Name Type Description
ssn string SSN of the card holder (numbers only). Either an SSN or a passport number is required.
passport string Passport number of the card holder. Either an SSN or a passport is required.
nationality ISO31661-Alpha2 string Required on passport only. Two letters representing the card holder nationality. (e.g. “US”).
fullName FullName Full name of the card holder.
dateOfBirth RFC3339 Date string Date of birth of the card holder (e.g. "2001-08-15").
address Address Address of the card holder.
phone Phone Phone of the card holder.
email string Email address of the card holder.
idempotencyKey string See Idempotency.
tags object See Tags.

Relationships

Name Type Description
account JSON:API Relationship The account the card belongs to. Holder of the account must be a business.

Response

Response is a JSON:API document.

Example Response:

{
  "data": {
    "type": "businessVirtualDebitCard",
    "id": "9",
    "attributes": {
      "createdAt": "2020-05-13T09:42:21.857Z",
      "last4Digits": "2074",
      "expirationDate": "2022-05",
      "address": {
        "street": "5230 Newell Rd",
        "street2": null,
        "city": "Palo Alto",
        "state": "CA",
        "postalCode": "94303",
        "country": "US"
      },
      "fullName": {
        "first": "Richard",
        "last": "Hendricks"
      },
      "phone": {
        "countryCode": "1",
        "number": "5555555666"
      },
      "email": "richard@piedpiper.com",
      "dateOfBirth": "2001-08-10",
      "ssn": "123456789",
      "status": "Inactive"
    },
    "relationships": {
      "account": {
        "data": {
          "type": "depositAccount",
          "id": "1"
        }
      },
      "customer": {
        "data": {
          "type": "businessCustomer",
          "id": "1"
        }
      }
    }
  }
}

201 Created

Field Type Description
data BusinessVirtualDebitCard The target resource after the operation was completed.

Displaying Sensitive Card Data

In order to display sensitive data (e.g. card number and CVV2) to a customer, without any of it passing through your systems (which requires PCI compliance), Unit utilizes a 3rd party service called Very Good Security or VGS for short.

VGS provides a JavaScript library (as well as iOS and Android SDKs) called VGS Show which allows easy integration with your UI components. VGS Show offloads the PCI compliance burden by enabling the encrypted transmission of sensitive card data from VGS directly to your cardholder.

The VGS Show JavaScript library enables you to securely display sensitive data in a webpage while safely isolating that sensitive data from your systems. VGS Show JavaScript library injects a secure iframe into your HTML. VGS hosts both the iframe, and the data on secure, compliant servers.

Integration steps

Example of creating a Customer Token for sensitive data:

curl -X POST 'https://api.s.unit.sh/customers/8/token' \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: Bearer ${TOKEN}' \
--data-raw '{
  "data":{
    "type":"customerToken",
    "attributes": {
      "scope": "cards-sensitive",
      "verificationToken": "i8FWKLBjXEg3TdeK93G3K9PKLzhbT6CRhn/VKkTsm....",
      "verificationCode": "203130"
    }
  }
}
'

Example of displaying card number and CVV2:

<!DOCTYPE html>
<html>
<head>
    <meta charSet="utf-8">
    <title></title>
    <style>
        iframe {
            height: 20px;
        }
    </style>
</head>
<body>
<h2>Sensitive Data example</h2>
<label>Card Number:</label>
<div id="pan"></div>
<label>CVV2:</label>
<div id="cvv2"></div>

<script type="text/javascript" src="https://js.verygoodvault.com/vgs-show/1.3/ACh8JJTM42LYxwe2wfGQxwj5.js"></script>
<script type="text/javascript">
    const show = VGSShow.create('tntazhyknp1');
    const customerToken = "<CUSTOMER TOKEN>"

    const cvv2iframe = show.request({
            name: 'data-text',
            method: 'GET',
            path: '/cards/<CARD ID>/secure-data/cvv2',
            headers: {
                "Authorization": "Bearer " + customerToken
            },
            htmlWrapper: 'text',
            jsonPathSelector: 'data.attributes.cvv2'
        });
    cvv2iframe.render('#cvv2');

    const paniframe = show.request({
            name: 'data-text',
            method: 'GET',
            path: '/cards/<CARD ID>/secure-data/pan',
            headers: {
                "Authorization": "Bearer " + customerToken
            },
            htmlWrapper: 'text',
            jsonPathSelector: 'data.attributes.pan'
        });
    paniframe.render('#pan');
</script>
</body>
</html>

Import the VGS Show library:

<script type="text/javascript" src="https://js.verygoodvault.com/vgs-show/1.3/ACh8JJTM42LYxwe2wfGQxwj5.js"></script>

Initialize the component:

const show = VGSShow.create('tntazhyknp1');

Provide a valid customer token:

const customerToken = "<CUSTOMER TOKEN>"

For instructions, see Create Customer Token.

Provide a valid card identifier

path: '/cards/<CARD ID>/secure-data/cvv2'

Additional resources

SDKs for iOS and Android and additional code examples can be found here.

Activate Card

In order to activate a new card, without any sensitive data passing through your systems (which requires PCI compliance), Unit utilizes a 3rd party service called Very Good Security or VGS for short.

VGS provides a JavaScript library (as well as iOS and Android SDKs) called VGS Collect which allows easy integration with your UI components. VGS Collect offloads the PCI compliance burden by enabling the encrypted transmission of sensitive card data from VGS directly to the card processor.

VGS Collect JavaScript library injects a secure iframe into your HTML. VGS hosts both the iframe, and the data on secure, compliant servers.

Integration steps

Example of creating a Customer Token for Activate Card:

curl -X POST 'https://api.s.unit.sh/customers/8/token' \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: Bearer ${TOKEN}' \
--data-raw '{
  "data":{
    "type":"customerToken",
    "attributes": {
      "scope": "cards-sensitive-write",
      "verificationToken": "i8FWKLBjXEg3TdeK93G3K9PKLzhbT6CRhn/VKkTsm....",
      "verificationCode": "203130"
    }
  }
}
'

Example of Activate Card:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>VGS Collect Credit Card Example</title>

    <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0/css/bootstrap.min.css"
          integrity="sha384-Gn5384xqQ1aoWXA+058RXPxPg6fy4IWvTNh0E263XmFcJlSAwiGgFAW/dAiS6JXm" crossorigin="anonymous">

    <script type="text/javascript" src="https://js.verygoodvault.com/vgs-collect/2.3.0/vgs-collect.js"></script>

    <style>
        body {
            padding: 25px;
        }

        span[id*="cc-"] {
            display: block;
            height: 40px;
            margin-bottom: 15px;
        }

        span[id*="cc-"] iframe {
            height: 100%;
            width: 100%;
        }

        pre {
            font-size: 12px;
        }

        .form-field {
            display: block;
            width: 100%;
            height: calc(2.25rem + 2px);
            padding: .375rem .75rem;
            font-size: 1rem;
            line-height: 1.5;
            color: #495057;
            background-color: #fff;
            background-clip: padding-box;
            border: 1px solid #ced4da;
            border-radius: .25rem;
            transition: border-color .15s ease-in-out,box-shadow .15s ease-in-out;
        }

        .form-field iframe {
            border: 0 none transparent;
            height: 100%;
            vertical-align: middle;
            width: 100%;
        }

        p {
            margin-bottom: 10px;
        }
    </style>
</head>
<body>
<main>
    <div class="row">
        <div class="col-md-4"></div>
        <div class="col-md-4">
            <div class="row card card-outline-secondary">
                <div class="card-body">
                    <h3 class="text-center">Activate Card</h3>
                    <hr>
                    <div class="alert alert-info p-2">
                        Please fill in and submit the form
                    </div>
                    <form id="cc-form">
                        <div class="form-group">
                            <label for="cc-cvv2">CVV2</label>
                            <span id="cc-cvv2" class="form-field">
                  <!--VGS Collect iframe for CVV2 field will be here!-->
                </span>
                            <label for="cc-expiration-date">Expiration Date</label>
                            <span id="cc-expiration-date" class="form-field">
                  <!--VGS Collect iframe for Expiration Date field will be here!-->
                </span>
                        </div>
                        <!--Submit form button-->
                        <button type="submit" class="btn btn-success btn-block">Submit</button>
                    </form>
                </div>
            </div>
        </div>
        <div class="col-md-4"></div>
    </div>
</main>

<!--Include script with VGS Collect form initialization-->
<script>
    // VGS Collect form initialization
    const form = VGSCollect.create("tntazhyknp1", "sandbox", function(state) {});
    const customerToken = "<CUSTOMER TOKEN>"

    form.field('#cc-cvv2', {
        type: 'card-security-code',
        name: 'data.attributes.cvv2',
        successColor: '#4F8A10',
        errorColor: '#D8000C',
        placeholder: '123',
        maxLength: 3,
        validations: ['required', 'validCardSecurityCode']
    });

    form.field('#cc-expiration-date', {
        type: 'card-expiration-date',
        name: 'data.attributes.expirationDate',
        successColor: '#4F8A10',
        errorColor: '#D8000C',
        placeholder: 'MM / YYYY',
        validations: ['required', 'validCardExpirationDate'],
        // Change to required experiation date format
        serializers: [form.SERIALIZERS.replace('(\\d{2})\\s\\/\\s(\\d{4})', '$2-$1')]
    });

    // Submit by executing a POST request.
    document.getElementById('cc-form')
        .addEventListener('submit', function(e) {
            e.preventDefault();
            form.submit('/cards/<CARD ID>/activate',
                {
                    mapDotToObject: 'true',
                    headers: {
                        "Content-Type": "application/vnd.api+json",
                        "Authorization": "Bearer " + customerToken
                    }
                },


                function(status, data) {
                    console.log(data);
                });
        }, function (errors) {
            console.log(errors);
        });
</script>
</body>
</html>

Import the VGS Collect library: <script type="text/javascript" src="https://js.verygoodvault.com/vgs-collect/2.6.0/vgs-collect.js"></script>

Initialize the component:

const form = VGSCollect.create("tntazhyknp1", "sandbox", function(state) {});

Provide a valid customer token:

const customerToken = "<CUSTOMER TOKEN>"

For instructions, see Create Customer Token.

Provide a valid card identifier

path: '/cards/<CARD ID>/activate'

Additional resources

SDKs for iOS and Android and additional code examples can be found here.

Set PIN

In order to set a new PIN, without any sensitive data passing through your systems (which requires PCI compliance), Unit utilizes a 3rd party service called Very Good Security or VGS for short.

VGS provides a JavaScript library (as well as iOS and Android SDKs) called VGS Collect which allows easy integration with your UI components. VGS Collect offloads the PCI compliance burden by enabling the encrypted transmission of sensitive card data from VGS directly to the card processor.

VGS Collect JavaScript library injects a secure iframe into your HTML. VGS hosts both the iframe, and the data on secure, compliant servers.

Integration steps

Example of creating a Customer Token for Set PIN:

curl -X POST 'https://api.s.unit.sh/customers/8/token' \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: Bearer ${TOKEN}' \
--data-raw '{
  "data":{
    "type":"customerToken",
    "attributes": {
      "scope": "cards-sensitive-write",
      "verificationToken": "i8FWKLBjXEg3TdeK93G3K9PKLzhbT6CRhn/VKkTsm....",
      "verificationCode": "203130"
    }
  }
}
'

Example of Set PIN:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>VGS Collect Credit Card Example</title>

    <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0/css/bootstrap.min.css"
          integrity="sha384-Gn5384xqQ1aoWXA+058RXPxPg6fy4IWvTNh0E263XmFcJlSAwiGgFAW/dAiS6JXm" crossorigin="anonymous">

    <script type="text/javascript" src="https://js.verygoodvault.com/vgs-collect/2.3.0/vgs-collect.js"></script>

    <style>
        body {
            padding: 25px;
        }

        span[id*="cc-"] {
            display: block;
            height: 40px;
            margin-bottom: 15px;
        }

        span[id*="cc-"] iframe {
            height: 100%;
            width: 100%;
        }

        pre {
            font-size: 12px;
        }

        .form-field {
            display: block;
            width: 100%;
            height: calc(2.25rem + 2px);
            padding: .375rem .75rem;
            font-size: 1rem;
            line-height: 1.5;
            color: #495057;
            background-color: #fff;
            background-clip: padding-box;
            border: 1px solid #ced4da;
            border-radius: .25rem;
            transition: border-color .15s ease-in-out,box-shadow .15s ease-in-out;
        }

        .form-field iframe {
            border: 0 none transparent;
            height: 100%;
            vertical-align: middle;
            width: 100%;
        }

        p {
            margin-bottom: 10px;
        }
    </style>
</head>
<body>
<main>
    <div class="row">
        <div class="col-md-4"></div>
        <div class="col-md-4">
            <div class="row card card-outline-secondary">
                <div class="card-body">
                    <h3 class="text-center">Set PIN</h3>
                    <hr>
                    <div class="alert alert-info p-2">
                        Please fill in and submit the form
                    </div>
                    <form id="cc-form">
                        <div class="form-group">
                            <label for="cc-pin">PIN</label>
                            <span id="cc-pin" class="form-field">
                  <!--VGS Collect iframe for PIN field will be here!-->
                </span>
                        </div>
                        <!--Submit form button-->
                        <button type="submit" class="btn btn-success btn-block">Submit</button>
                    </form>
                </div>
            </div>
        </div>
        <div class="col-md-4"></div>
    </div>
</main>

<!--Include script with VGS Collect form initialization-->
<script>
    // VGS Collect form initialization
    const form = VGSCollect.create("tntazhyknp1", "sandbox", function(state) {});
    const customerToken = "<CUSTOMER TOKEN>"

    // Create VGS Collect field for PIN
    form.field('#cc-pin', {
        type: 'text',
        name: 'data.attributes.pin',
        successColor: '#4F8A10',
        errorColor: '#D8000C',
        placeholder: '1234',
        maxLength: 6,
        validations: ['required', '/^([0-9]{4,6})$/'],
    });

    // Submit by executing a POST request.
    document.getElementById('cc-form')
        .addEventListener('submit', function(e) {
            e.preventDefault();
            form.submit('/cards/<CARD ID>/secure-data/pin',
                {
                    mapDotToObject: 'true',
                    headers: {
                        "Content-Type": "application/vnd.api+json",
                        "Authorization": "Bearer " + customerToken
                    }
                },


                function(status, data) {
                    console.log(data);
                });
        }, function (errors) {
            console.log(errors);
        });
</script>
</body>
</html>

Import the VGS Collect library: <script type="text/javascript" src="https://js.verygoodvault.com/vgs-collect/2.6.0/vgs-collect.js"></script>

Initialize the component:

const form = VGSCollect.create("tntazhyknp1", "sandbox", function(state) {});

Provide a valid customer token:

const customerToken = "<CUSTOMER TOKEN>"

For instructions, see Create Customer Token.

Provide a valid card identifier

path: '/cards/<CARD ID>/secure-data/pin'

Additional resources

SDKs for iOS and Android and additional code examples can be found here.

Report Stolen

Report card as stolen.

curl -X POST 'https://api.s.unit.sh/cards/6/report-stolen' \
-H "Authorization: Bearer ${TOKEN}"
Verb POST
Url https://api.s.unit.sh/cards/:cardId/report-stolen
Required Scope cards-write

Response

Response is a JSON:API document.

200 OK

Field Type Description
data IndividualDebitCard or BusinessDebitCard or IndividualVirtualDebitCard or BusinessVirtualDebitCard Card resource, distinguished by the type field.

Report Lost

Report card as lost.

curl -X POST 'https://api.s.unit.sh/cards/5/report-lost' \
-H "Authorization: Bearer ${TOKEN}"
Verb POST
Url https://api.s.unit.sh/cards/:cardId/report-lost
Required Scope cards-write

Response

Response is a JSON:API document.

200 OK

Field Type Description
data IndividualDebitCard or BusinessDebitCard or IndividualVirtualDebitCard or BusinessVirtualDebitCard Card resource, distinguished by the type field.

Close Card

Close a card.

curl -X POST 'https://api.s.unit.sh/cards/7/close' \
-H "Authorization: Bearer ${TOKEN}"
Verb POST
Url https://api.s.unit.sh/cards/:cardId/close
Required Scope cards-write

Response

Response is a JSON:API document.

200 OK

Field Type Description
data IndividualDebitCard or BusinessDebitCard or IndividualVirtualDebitCard or BusinessVirtualDebitCard Card resource, distinguished by the type field.

Freeze Card

Freeze a card (temporarily block a card).

curl -X POST 'https://api.s.unit.sh/cards/8/freeze' \
-H "Authorization: Bearer ${TOKEN}"
Verb POST
Url https://api.s.unit.sh/cards/:cardId/freeze
Required Scope cards-write

Response

Response is a JSON:API document.

200 OK

Field Type Description
data IndividualDebitCard or BusinessDebitCard or IndividualVirtualDebitCard or BusinessVirtualDebitCard Card resource, distinguished by the type field.

Unfreeze Card

Unfreeze a frozen card.

curl -X POST 'https://api.s.unit.sh/cards/8/unfreeze' \
-H "Authorization: Bearer ${TOKEN}"
Verb POST
Url https://api.s.unit.sh/cards/:cardId/unfreeze
Required Scope cards-write

Response

Response is a JSON:API document.

200 OK

Field Type Description
data IndividualDebitCard or BusinessDebitCard or IndividualVirtualDebitCard or BusinessVirtualDebitCard Card resource, distinguished by the type field.

Replace Card

Creates and ships a replacement physical debit card to an individual or business card holder. The replacement card has the same expiration date and PIN as the original card.

Example Request:

curl -X POST 'https://api.s.unit.sh/cards/8/replace' \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: Bearer ${TOKEN}' \
--data-raw '{
  "data":{
    "type":"replaceCard",
    "attributes": {
      "shippingAddress": {
        "street": "5230 Newell Rd",
        "city": "Palo Alto",
        "state": "CA",
        "postalCode": "94303",
        "country": "US"
      }
    }
  }
}'
Verb POST
Url https://api.s.unit.sh/cards/:cardId/replace
Required Scope cards-sensitive-write
Data Type replaceCard

Attributes

Name Type Description
shippingAddress Address Address to ship the card to. Optional, if not specified, the address provided during card creation is reused.

Response

Response is a JSON:API document.

Example Response:

{
  "data": {
    "type": "individualDebitCard",
    "id": "8",
    "attributes": {
      "createdAt": "2020-05-13T09:07:47.645Z",
      "last4Digits": "1234",
      "expirationDate": "2022-05",
      "shippingAddress": {
        "street": "5230 Newell Rd",
        "street2": null,
        "city": "Palo Alto",
        "state": "CA",
        "postalCode": "94303",
        "country": "US"
      },
      "status": "Inactive"
    },
    "relationships": {
      "account": {
        "data": {
          "type": "account",
          "id": "2"
        }
      },
      "customer": {
        "data": {
          "type": "customer",
          "id": "2"
        }
      }
    }
  }
}

200 OK

Field Type Description
data IndividualDebitCard or BusinessDebitCard Card resource, distinguished by the type field.

Get by Id

Get a card resource by id.

curl -X GET 'https://api.s.unit.sh/cards/1?include=customer' \
-H "Authorization: Bearer ${TOKEN}"
Verb GET
Url https://api.s.unit.sh/cards/{id}
Required Scope cards

Query Parameters

Name Type Default Description
include string (empty) Optional. A comma-separated list of related resources to include in the response. Related resources include: customer, account. See Getting Related Resources

Response

Response is a JSON:API document.

200 OK

Field Type Description
data IndividualDebitCard or BusinessDebitCard or IndividualVirtualDebitCard or BusinessVirtualDebitCard Card resource, distinguished by the type field.
included Array of DepositAccount or Customer Array of resources requested by the include query parameter.

List

List cards. Filtering and paging can be applied.

curl -X GET 'https://api.s.unit.sh/cards?page[limit]=20&page[offset]=0&include=customer' \
-H "Authorization: Bearer ${TOKEN}"
Verb GET
Url https://api.s.unit.sh/cards
Required Scope cards

Query Parameters

Name Type Default Description
page[limit] integer 100 Maximum number of resources that will be returned. Maximum is 1000 resources. See Pagination.
page[offset] integer 0 Number of resources to skip. See Pagination.
filter[accountId] string (empty) Optional. Filters the results by the specified account id.
filter[customerId] string (empty) Optional. Filters the results by the specified customer id.
include string (empty) Optional. A comma-separated list of related resources to include in the response. Related resources include: customer, account. See Getting Related Resources

Response

Example Response:

{
  "data": [
    {
      "type": "individualDebitCard",
      "id": "1",
      "attributes": {
        "createdAt": "2020-05-10T16:45:02.272Z",
        "last4Digits": "1234",
        "expirationDate": "2022-05",
        "status": "Active"
      },
      "relationships": {
        "account": {
          "data": {
            "type": "depositAccount",
            "id": "1"
          }
        },
        "customer": {
          "data": {
            "type": "individualCustomer",
            "id": "2"
          }
        }
      }
    },
    {
      "type": "businessDebitCard",
      "id": "4",
      "attributes": {
        "createdAt": "2020-05-10T20:37:48.069Z",
        "last4Digits": "1234",
        "expirationDate": "2022-05",
        "shippingAddress": {
          "street": "5230 Newell Rd",
          "street2": null,
          "city": "Palo Alto",
          "state": "CA",
          "postalCode": "94303",
          "country": "US"
        },
        "address": {
          "street": "5230 Newell Rd",
          "street2": null,
          "city": "Palo Alto",
          "state": "CA",
          "postalCode": "94303",
          "country": "US"
        },
        "fullName": {
          "first": "Richard",
          "last": "Hendricks"
        },
        "phone": {
          "countryCode": "1",
          "number": "5555555789"
        },
        "email": "richard@piedpiper.com",
        "dateOfBirth": "2001-08-10",
        "ssn": "123456789",
        "status": "Active"
      },
      "relationships": {
        "account": {
          "data": {
            "type": "depositAccount",
            "id": "1"
          }
        },
        "customer": {
          "data": {
            "type": "businessCustomer",
            "id": "1"
          }
        }
      }
    }
  ]
}

Response is a JSON:API document.

200 OK

Field Type Description
data Array of IndividualDebitCard or BusinessDebitCard or IndividualVirtualDebitCard or BusinessVirtualDebitCard Array of card resources, distinguished by the type field.
included Array of DepositAccount or Customer Array of resources requested by the include query parameter.

Update

Update a debit card.

Verb PATCH
Url https://api.s.unit.sh/cards/:cardId
Required Scope cards-write

Example of update business debit card:

curl -X PATCH 'https://api.s.unit.sh/cards/:cardId' \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: Bearer ${TOKEN}' \
--data-raw '{
  "data":{
    "type":"businessDebitCard",
    "attributes": {
      "shippingAddress": {
        "street": "5231 Newell Rd",
        "street2": null,
        "city": "Palo Alto",
        "state": "CA",
        "postalCode": "94301",
        "country": "US"
      },
      "address": {
        "street": "5231 Newell Rd",
        "street2": null,
        "city": "Palo Alto",
        "state": "CA",
        "postalCode": "94301",
        "country": "US"
      },
      "email": "richard@piedpiper.com",
      "phone": {
        "countryCode": "1",
        "number": "5555555556"
      }
    }
  }
}'

Update Individual Debit Card

Name Type Description
shippingAddress Address Address to ship the card to.
To modify or add specify the key and value.
To delete a key specify the key name and null for the value.
design string Card design name. To modify or add specify the key and value.
tags object See Updating Tags.

Update Business Debit Card

Name Type Description
shippingAddress Address Address to ship the card to.
To modify or add specify the key and value.
To delete a key specify the key name and null for the value.
address Address Address of the card holder.
To modify or add specify the new address.
phone Phone Phone of the card holder.
To modify or add specify the new phone number.
email string Email address of the card holder.
To modify or add specify the new email address.
design string Card design name. To modify or add specify the key and value.
tags object See Updating Tags.

Update Individual Virtual Debit Card

Name Type Description
tags object See Updating Tags.

Update Business Virtual Debit Card

Name Type Description
address Address Address of the card holder.
To modify or add specify the new address.
phone Phone Phone of the card holder.
To modify or add specify the new phone number.
email string Email address of the card holder.
To modify or add specify the new email address.
tags object See Updating Tags.

Response

Response is a JSON:API document.

200 OK

Field Type Description
data IndividualDebitCard Or BusinessDebitCard Or
BusinessVirtualDebitCard Or IndividualVirtualDebitCard resource
The target resource after the operation was completed.

Counterparties

The counterparty resource represents the other party that participates in a financial transaction.

When a customer is expected to send funds to same counterparty on multiple occasions you may create a counterparty resource and re-use it by creating an ACH payment to linked Counterparty, instead of the customer typing the routing number and account number repeatedly.

When creating an API Token Unit recommends not to select the payments-write and counterparties-write, however we do recommend selecting payments-write-counterparty scope, which allows making payments to counterparty resource only.

When using the recommended scopes for API Token you would first need to Create a Customer Token (along with two-factor authentication) in order to create the counterparty resource.

The counterparty resource also allows you to make (automated) payments without creating a Customer Token or selecting sensitive scopes for the API Token, by using ACH payment to linked Counterparty and API Token with only payments-write-counterparty selected.

This adds another layer of security, because the API Token alone cannot make payments to counterparties which are not created and approved by the customer.

Create Counterparty

Creates a counterparty for a specific customer.

Example Request:

curl -X POST 'https://api.s.unit.sh/counterparties' \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: Bearer ${TOKEN}' \
--data-raw '{
  "data": {
    "type": "achCounterparty",
    "attributes": {
      "name": "Joe Doe",
      "routingNumber": "011000138",
      "accountNumber": "123",
      "accountType": "Checking",
      "type": "Person"
    },
    "relationships": {
      "customer": {
        "data": {
          "type": "customer",
          "id": "111111"
        }
      }
    }
  }
}'
Verb POST
Url https://api.s.unit.sh/counterparties
Required Scope counterparties-write
Data Type achCounterparty

Attributes

Name Type Description
name string The account holder's name (whether an individual or a business).
routingNumber string Valid 9-digit ABA routing transit number.
accountNumber string Bank account number.
accountType string Either Checking or Savings.
type string Either Business, Person or Unknown.

Relationships

Name Type Description
customer JSON:API Relationship The customer that the counterparty belongs to.

Response

Response is a JSON:API document.

Example Response:

{
  "data": {
    "type": "achCounterparty",
    "id": "8",
    "attributes": {
      "createdAt": "2020-05-13T09:07:47.645Z",
      "name": "Joe Doe",
      "routingNumber": "011000138",
      "bank": "Bank Of America",
      "accountNumber": "123",
      "accountType": "Checking",
      "type": "Person",
      "permissions": "CreditOnly"
    },
    "relationships": {
      "customer": {
        "data": {
          "type": "customer",
          "id": "111111"
        }
      }
    }
  }
}

201 Created

Field Type Description
data ACH Counterparty The target resource after the operation was completed.

Create Counterparty with Plaid token

Creates a counterparty for a specific customer

Example Request:

curl -X POST 'https://api.s.unit.sh/counterparties' \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: Bearer ${TOKEN}' \
--data-raw '{
    "data": {
      "type": "achCounterparty",
      "attributes": {
        "name": "Sherlock Holmes",
        "plaidProcessorToken": "processor-5a62q307-ww0a-6737-f6db-pole26004556",
        "type": "Person"
      },
      "relationships": {
        "customer": {
          "data": {
            "type": "customer",
            "id": "111111"
          }
        }
      }
    }
  }'
Verb POST
Url https://api.s.unit.sh/counterparties
Required Scope counterparties-write
Data Type achCounterparty

Attributes

Name Type Description
type string Either Business, Person or Unknown
name string The account holder's name (whether an individual or a business).
plaidProcessorToken string Plaid integration token
See Plaid processor token

Relationships

Name Type Description
customer JSON:API Relationship The customer that the counterparty belongs to.

Delete

Delete a counterparty resource by id.

curl -X DELETE 'https://api.s.unit.sh/counterparties/1' \
-H "Authorization: Bearer ${TOKEN}"
Verb DELETE
Url https://api.s.unit.sh/counterparties/{id}
Required Scope counterparties

Response

204 No Content

Get by Id

Get a counterparty resource by id.

curl -X GET 'https://api.s.unit.sh/counterparties/:counterpartyId' \
-H "Authorization: Bearer ${TOKEN}"
Verb GET
Url https://api.s.unit.sh/counterparties/{id}
Required Scope counterparties

Response

Response is a JSON:API document.

200 OK

Field Type Description
data ACH Counterparty Counterparty resource.

List

List counterparties. Filtering and paging can be applied.

curl -X GET 'https://api.s.unit.sh/counterparties?page[limit]=20&page[offset]=0' \
-H "Authorization: Bearer ${TOKEN}"
Verb GET
Url https://api.s.unit.sh/counterparties
Required Scope counterparties

Query Parameters

Name Type Default Description
page[limit] integer 100 Maximum number of resources that will be returned. Maximum is 1000 resources. See Pagination.
page[offset] integer 0 Number of resources to skip. See Pagination.
filter[customerId] string (empty) Optional. Filters the results by the specified customer id.

Response

Example Response:

{
  "data": [
    {
      "type": "achCounterparty",
      "id": "8",
      "attributes": {
        "createdAt": "2020-05-13T09:07:47.645Z",
        "name": "Joe Doe",
        "routingNumber": "123456789",
        "accountNumber": "123",
        "accountType": "Checking",
        "type": "Person",
        "permissions": "CreditOnly"
      },
      "relationships": {
        "customer": {
          "data": {
            "type": "customer",
            "id": "111111"
          }
        }
      }
    }
  ]
}

Response is a JSON:API document.

200 OK

Field Type Description
data Array of ACH Counterparty Array of counterparty resources.

Update Counterparty

Update a Counterparty. Relink existing counterparty with a new Plaid processor token.

Update a counterparty:

curl -X PATCH 'https://api.s.unit.sh/counterparties/:counterpartyId' \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: Bearer ${TOKEN}' \
--data-raw '{
  "data": {
    "type": "counterparty",
    "attributes": {
      "plaidProcessorToken": "processor-sandbox-b14ad1fd-3398-46a8-a316-5bf574fc2459"
    }
  }
}'
Verb PATCH
Url https://api.s.unit.sh/counterparties/:counterpartyId

Attributes

Name Type Description
plaidProcessorToken string Plaid integration token
See Plaid processor token

Response

Response is a JSON:API document.

200 OK

Example Response:

{
  "data": {
    "type": "achCounterparty",
    "id": "8",
    "attributes": {
      "createdAt": "2020-05-13T09:07:47.645Z",
      "name": "Joe Doe",
      "routingNumber": "011000138",
      "bank": "Bank Of America",
      "accountNumber": "123",
      "accountType": "Checking",
      "type": "Person",
      "permissions": "CreditOnly"
    },
    "relationships": {
      "customer": {
        "data": {
          "type": "customer",
          "id": "111111"
        }
      }
    }
  }
}
Field Type Description
data ACH Counterparty The target resource after the operation was completed.

Transactions

A transaction is an individual entry that represents any financial movement within an account. The Transaction resource represents confirmed transactions that were posted to the account, including their source, amount, and direction.

Unit currently supports the following types of transactions.

Type Description
Originated ACH An ACH payment originated from a deposit account.
Received ACH An ACH payment received by a deposit account.
Returned ACH An ACH payment returned by the bank.
Wire A wire transaction, either received or sent.
Book A payment between two accounts on the same bank.
Purchase A purchase via debit card.
ATM A deposit or a withdrawal of funds from an ATM with a debit card.
Fee Fees incurred for a transaction.
Interest An Interest payment to a deposit account.
Card Reversal A reversal of a previous card transaction.
Card Transaction A transaction that represents various card transactions that are not Purchase or ATM transactions. Those might be split in the future into different types.
Release A transaction releasing funds from a batch account.
Adjustment Manual Adjustment is made in situations where the correction of an amount, or a reverse of a completed transaction is needed.
Dispute Dispute transaction is created in order to credit or debit a customer for an ongoing card or ACH dispute. For example, when provisional credit is provided, the customer account would be credited using the Dispute Transaction.

In addition to their own specific fields, all transaction types are guaranteed to contain the following top-level fields:

Field type Description
direction string The direction in which the funds flow- Debit or Credit.
amount integer The amount (cents) of the transaction.
balance integer The account balance (cents) after the transaction.
summary string Human-friendly summary of the transaction.

Get by Id

Get a transaction by transaction id and account id.

curl -X GET 'https://api.s.unit.sh/accounts/:accountId/transactions/:transactionId' \
-H "Authorization: Bearer ${TOKEN}"
Verb GET
Url https://api.s.unit.sh/accounts/:accountId/transactions/{transactionId}
Required Scope transactions

Query Parameters

Name Type Default Description
filter[customerId] string (none) Optional. Filters the result by the specified customer id.
include string (empty) Optional. A comma-separated list of related resources to include in the response. Related resources include: customer, account. See Getting Related Resources

Response

Response is a JSON:API document.

200 OK

Field Type Description
data One of OriginatedAchTransaction
ReceivedAchTransaction
BookTransaction
PurchaseTransaction
AtmTransaction
FeeTransaction
CardTransaction
CardReversalTransaction
Transaction resources.
included Array of DepositAccount or Customer Array of resources requested by the include query parameter.

List

List transaction resources. Filtering, paging and sorting can be applied.

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

Query Parameters

Name Type Default Description
page[limit] integer 100 Maximum number of resources that will be returned. Maximum is 1000 resources. See Pagination.
page[offset] integer 0 Number of resources to skip. See Pagination.
filter[accountId] string (empty) Optional. Filters the results by the specified account id.
filter[customerId] string (empty) Optional. Filters the results by the specified customer id.
filter[query] string (empty) Optional. search term according to the Full-Text Search Rules.
filter[tags] Tags (JSON) (empty) Optional. Filter Transactions by Tags.
filter[since] RFC3339 Date string (empty) Optional. Filters the Transactions that occurred after the specified date. e.g. 2020-01-13T16:01:19.346Z
filter[until] RFC3339 Date string (empty) Optional. Filters the Transactions that occurred before the specified date. e.g. 2020-01-02T20:06:23.486Z
filter[cardId] string (empty) Optional. Filters the results by the specified card id.
sort string sort=-createdAt Optional. Leave empty or provide sort=createdAt for ascending order. Provide sort=-createdAt (leading minus sign) for descending order.
include string (empty) Optional. A comma-separated list of related resources to include in the response. Related resources include: customer, account. See Getting Related Resources

Response

Example Response:

{
  "data": [
    {
      "type": "originatedAchTransaction",
      "id": "337",
      "attributes": {
        "createdAt": "2020-09-06T07:51:02.570Z",
        "direction": "Credit",
        "amount": 10000,
        "balance": 10000,
        "summary": "Counterparty: Unit Inc | Description: Funding",
        "description": "Funding",
        "counterparty": {
          "name": "Unit Inc",
          "routingNumber": "812345678",
          "accountNumber": "1",
          "accountType": "Checking"
        }
      },
      "relationships": {
        "account": {
          "data": {
            "type": "account",
            "id": "10001"
          }
        },
        "customer": {
          "data": {
            "type": "customer",
            "id": "3"
          }
        }
      }
    },
    {
      "type": "feeTransaction",
      "id": "338",
      "attributes": {
        "createdAt": "2020-09-06T07:51:03.094Z",
        "direction": "Debit",
        "amount": 10,
        "balance": 9990,
        "summary": "Fee - Funding"
      },
      "relationships": {
        "account": {
          "data": {
            "type": "account",
            "id": "10001"
          }
        },
        "customer": {
          "data": {
            "type": "customer",
            "id": "3"
          }
        },
        "relatedTransaction": {
          "data": {
            "type": "transaction",
            "id": "337"
          }
        }
      }
    }
  ]
}

Response is a JSON:API document.

200 OK

Field Type Description
data Array of OriginatedAchTransaction or
ReceivedAchTransaction or
BookTransaction or
PurchaseTransaction or
AtmTransaction or
FeeTransaction or
CardTransaction or
CardReversalTransaction
Array of transaction resources.
included Array of DepositAccount or Customer Array of resources requested by the include query parameter.

Update

Example Request:

Update Transaction

{
  "data": {
    "type": "transaction",
    "attributes": {
      "tags": {
        "trackUserId": 1234
      }
    }
  }
}
Verb PATCH
Url https://api.s.unit.sh/accounts/:accountId/transactions/:transactionId
Required Scope transactions-write

Attributes

Name Type Description
tags object See Updating Tags.

Response

Response is a JSON:API document.

200 OK

Field Type Description
data One of OriginatedAchTransaction
ReceivedAchTransaction
BookTransaction
PurchaseTransaction
AtmTransaction
FeeTransaction
CardTransaction
CardReversalTransaction
Transaction resources.

Authorizations

The authorization (also authorization hold) process is an essential step in completing a card transaction. During authorization, the merchant receives the card holder’s information and verifies that the card is valid and that the card holder has sufficient funds to cover the amount of the transaction. Most merchants proceed immediately from authorization to the completion of the transaction, but they have the option to place a hold instead.

An authorization effectively “reserves” a certain amount of the card holder’s available funds for the merchant upon completion of the card transaction. The amount of the authorization is made unavailable to the card holder, but it isn’t transferred to the merchant’s account—not yet. When the transaction is settled, the authorization will be removed, and the card holder is charged the actual, final purchase amount.

The authorized amount will be included in the card holder account hold amount and will be reflected in the account available amount (see Deposit Account)

Get by Id

Get an authorization resource by id.

curl -X GET 'https://api.s.unit.sh/authorizations/1' \
-H "Authorization: Bearer ${TOKEN}"
Verb GET
Url https://api.s.unit.sh/authorizations/{id}
Required Scope authorizations

Response

Response is a JSON:API document.

200 OK

Field Type Description
data Authorization Authorization resource.

Find

Find authorizations. Filtering and paging can be applied.

curl -X GET 'https://api.s.unit.sh/authorizations?page[limit]=20&page[offset]=0' \
-H "Authorization: Bearer ${TOKEN}"
Verb GET
Url https://api.s.unit.sh/authorizations
Required Scope authorizations

Query Parameters

Name Type Default Description
page[limit] integer 100 Maximum number of resources that will be returned. Maximum is 1000 resources.
page[offset] integer 0 Number of resources to skip.
filter[accountId] string (empty) Optional. Filters the results by the specified account id.
filter[customerId] string (empty) Optional. Filters the results by the specified customer id.

Response

Example Response:

{
  "data": [
    {
      "type": "authorization",
      "id": "90",
      "attributes": {
        "createdAt": "2021-02-16T07:40:44.970Z",
        "amount": 2000,
        "cardLast4Digits": "",
        "merchant": {
          "name": "Europcar Mobility Group",
          "type": 3381,
          "category": "EUROP CAR",
          "location": "Cupertino, CA"
        }
      },
      "relationships": {
        "customer": {
          "data": {
            "type": "customer",
            "id": "10000"
          }
        },
        "account": {
          "data": {
            "type": "account",
            "id": "10001"
          }
        }
      }
    }
  ]
}

Response is a JSON:API document.

200 OK

Field Type Description
data Array of Authorization Array of authorization resources.

Batch Payments

A batch payment is any incoming payment into a batch account, which is a type of organization account. Once a batch payment is received, you are expected to split it between multiple customer accounts in your organization. This action is known as Release.

Batch accounts are meant to hold funds for a short period of time (typically less than a day). They serve use cases that deposit accounts cannot serve for compliance reasons. One such use case is send funds representing N businesses from a payment processor (e.g. WePay or Stripe) into N accounts under the same N businesses on Unit.

Batch Account

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

Example Response

{
    "data": {
        "type": "batchAccount",
        "id": "10104",
        "attributes": {
            "createdAt": "2020-12-09T12:17:49.849Z",
            "name": "Pied Piper batch account",
            "routingNumber": "812345678",
            "accountNumber": "1000000104",
            "balance": 0,
            "hold": 0
        },
        "relationships": {
            "org": {
                "data": {
                    "type": "org",
                    "id": "1"
                }
            }
        }
    }
}

A batch account is a type of organization account. You may instruct other institutions or payment processors to send funds directly into it, by sharing its routing number and account number.

Create Batch Releases

Example Request:

curl -X POST 'https://api.s.unit.sh/batch-releases' \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: Bearer ${TOKEN}' \
--data-raw '{
  "data":[
    {
      "type": "batchRelease",
      "attributes": {
        "amount": 3000,
        "description": "Gift",
        "senderName": "Sherlock Holmes",
        "senderAccountNumber": "4581133972",
        "senderAddress": {
          "street": "221B Baker Street",
          "city": "London",
          "postalCode": "NW1 6XE",
          "country": "GB"
        }
      },
      "relationships": {
        "batchAccount": {
          "data": {
            "type": "batchAccount",
            "id": "10104"
          }
        },
        "receiver": {
          "data": {
            "type": "depositAccount",
            "id": "10097"
          }
        }
      }
    },
    {
      "type":"batchRelease",
      "attributes": {
        "amount": 2000,
        "description": "Purchase",
        "senderName": "Peter Parker",
        "senderAccountNumber": "5324131257",
        "senderAddress": {
          "street": "5230 Newell Rd",
          "city": "Palo Alto",
          "state": "CA",
          "postalCode": "94303",
          "country": "US"
        }
      },
      "relationships": {
        "batchAccount": {
          "data": {
            "type": "batchAccount",
            "id": "10104"
          }
        },
        "receiver": {
          "data": {
            "type": "depositAccount",
            "id": "10017"
          }
        }
      }
    }]
}'

Release is the act of splitting a single batch payment between multiple customer accounts in your organization. When creating releases, you are required to provide compliance information for the original senders of the funds.

Verb POST
Url https://api.s.unit.sh/batch-releases
Required Scope batch-releases-write
Data Type batchRelease

Attributes

Name Type Description
amount integer The amount (in cents) to move from the batch account to the receiver account.
description string Description of the payment (maximum of 50 characters).
senderName string Sender name for the payment (maximum of 255 characters).
senderAddress Address Sender address for the payment.
senderAccountNumber string A unique identifier for the sender of the payment (maximum of 17 characters). As an example, when the payment comes from a card processor, this identifier may be set to the BIN followed by the last four digits of the card used.
tags object See Tags will be passed to the related Release Transaction.

Relationships

Name Type Description
batchAccount JSON:API Relationship The batch account to release the funds from.
receiver JSON:API Relationship The receiver account to release the funds to.

Response

Example Response:

{
  "data":[
    {
      "type": "batchRelease",
      "id": "100123",
      "attributes": {
        "amount": 3000,
        "description": "Gift",
        "senderName": "Sherlock Holmes",
        "senderAccountNumber": "4581133972",
        "senderAddress": {
          "street": "221B Baker Street",
          "city": "London",
          "postalCode": "NW1 6XE",
          "country": "GB"
        }
      },
      "relationships": {
        "batchAccount": {
          "data": {
            "type": "batchAccount",
            "id": "10104"
          }
        },
        "receiver": {
          "data": {
            "type": "depositAccount",
            "id": "10097"
          }
        }
      }
    },
    {
      "type":"batchRelease",
      "id": "100125",
      "attributes": {
        "amount": 2000,
        "description": "Purchase",
        "senderName": "Peter Parker",
        "senderAccountNumber": "5324131257",
        "senderAddress": {
          "street": "5230 Newell Rd",
          "city": "Palo Alto",
          "state": "CA",
          "postalCode": "94303",
          "country": "US"
        }
      },
      "relationships": {
        "batchAccount": {
          "data": {
            "type": "batchAccount",
            "id": "10104"
          }
        },
        "receiver": {
          "data": {
            "type": "depositAccount",
            "id": "10017"
          }
        }
      }
    }]
}

Response is a JSON:API document.

201 Created

Field Type Description
data Array of BatchRelease Array of batch release resources.

Simulations (Sandbox only)

Unit's Sandbox environment provides additional operations on top of the regular APIs. Those operations allow you to easily test and simulate activities that would normally take a long time or require interaction with the external world.

A common example for testing would be Simulating a Received ACH Payment to create funds in an account, followed by Simulating a Card Purchase to spend those funds.

Application Statuses

By default, all applications in our sandbox will be approved immediately. Below are ways to simulate other statuses:

Status Description
PendingReview Individual application: set the SSN on the application to 000000004. Business application: set the SSN of the Officer or any Beneficial Owner on the application to 000000004.
AwaitingDocuments Individual application: set the SSN on the application to 000000002 to simulate AwaitingDocuments for Address Verification, or 000000003 to simulate AwaitingDocuments for Id Document, or 000000006 to simulate AwaitingDocuments for Social Security Card. Business application: set the SSN of the Officer on the application to 000000005.
Denied Individual application: set the SSN on the application to 000000001.

Approve Application

Example Request:

curl -X POST 'https://api.s.unit.sh/sandbox/applications/10001/approve' \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: Bearer ${TOKEN}' \
--data-raw '{
  "data": {
    "type": "applicationApprove",
    "attributes": {
      "reason": "sandbox"
    }
  }
}'

Approves an Application under PendingReview or AwaitingDocuments status. The Customer Created webhook event will be fired.

Verb POST
Url https://api.s.unit.sh/sandbox/applications/{applicationId}/approve
Data Type applicationApprove

Deny Application

Example Request:

curl -X POST 'https://api.s.unit.sh/sandbox/applications/10001/deny' \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: Bearer ${TOKEN}' \
--data-raw '{
  "data": {
    "type": "applicationDeny",
    "attributes": {
      "reason": "sandbox"
    }
  }
}'

Denies an Application under PendingReview or AwaitingDocuments status. The Application Denied webhook event will be fired.

Verb POST
Url https://api.s.unit.sh/sandbox/applications/{applicationId}/deny
Data Type applicationDeny

Approve Document

Example Request:

curl -X POST 'https://api.s.unit.sh/sandbox/applications/10001/documents/1/approve' \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: Bearer ${TOKEN}' \
--data-raw '{}'

Approves an Application Document. The Document Approved webhook event will be fired.

Verb POST
Url https://api.s.unit.sh/sandbox/applications/{applicationId}/documents/{documentId}/approve

Reject Document

Example Request:

curl -X POST 'https://api.s.unit.sh/sandbox/applications/10001/documents/1/reject' \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: Bearer ${TOKEN}' \
--data-raw '{
  "data": {
    "type": "documentReject",
    "attributes": {
      "reason": "blurry image",
      "reasonCode": "PoorQuality"
    }
  }
}'

Rejects an Application Document. The Document Rejected webhook event will be fired.

Verb POST
Url https://api.s.unit.sh/sandbox/applications/{applicationId}/documents/{documentId}/reject
Data Type documentReject

Receive ACH payment

Example Request:

curl -X POST 'https://api.s.unit.sh/sandbox/payments' \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: Bearer ${TOKEN}' \
--data-raw '{
  "data":{
    "type":"achPayment",
    "attributes": {
      "amount": 10000,
      "direction": "Credit",
      "description": "Payment from Sandbox"
    },
    "relationships": {
      "account": {
        "data": {
          "type": "depositAccount",
          "id": "1000"
        }
      }
    }
  }
}'

This API allows you to simulate an incoming ACH payment with the specified amount (in cents) for testing purposes.

Verb POST
Url https://api.s.unit.sh/sandbox/payments
Data Type achPayment

Attributes

Name Type Description
amount integer The amount (in cents).
direction string The direction in which the funds flow (currently, only Credit is supported).
description string Payment description (maximum of 50 characters).

Relationships

Name Type Description
account JSON:API Relationship The Deposit Account receiving the payment.

Example Response:

{
  "data": {
      "type": "achPayment",
      "id": "3",
      "attributes": {
          "createdAt": "2020-06-29T13:17:59.816Z",
          "amount": 10000,
          "direction": "Credit",
          "description": "Payment from Sandbox",
          "status": "Sent",
          "reason": null
      },
      "relationships": {
          "account": {
              "data": {
                  "type": "depositAccount",
                  "id": "1000"
              }
          },
          "customer": {
              "data": {
                  "type": "individualCustomer",
                  "id": "1"
              }
          }
      }
  }
}

Note: the status for the sandbox payment requests is always Sent. Please refer to ACH Status for more information about the status codes.

Transmit ACH payment

Example Request:

curl -X POST 'https://api.s.unit.sh/sandbox/ach/transmit' \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: Bearer ${TOKEN}' \
--data-raw '{
  "data":{
    "type":"transmitAchPayment",
    "relationships": {
      "payment": {
        "data": {
          "type": "achPayment",
          "id": "10"
        }
      }
    }
  }
}'

This API allows you to simulate a file transmission to the network for an existing ACH payment with Pending status. After transmission, the status would change to Sent for ACH Credit payment and Clearing for ACH Debit payment.

Verb POST
Url https://api.s.unit.sh/sandbox/ach/transmit
Data Type transmitAchPayment

Relationships

Name Type Description
payment JSON:API Relationship The ACH Payment to transmit.

Example Response:

{
  "data": {
    "type": "achPayment",
    "id": "10",
    "attributes": {
      "createdAt": "2021-03-09T15:02:01.543Z",
      "amount": 10000,
      "direction": "Debit",
      "description": "Payment from Sandbox",
      "status": "Clearing"
    },
    "relationships": {
      "account": {
        "data": {
          "type": "account",
          "id": "10001"
        }
      },
      "customer": {
        "data": {
          "type": "customer",
          "id": "10000"
        }
      }
    }
  }
}

Clear ACH payment

Example Request:

curl -X POST 'https://api.s.unit.sh/sandbox/ach/clear' \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: Bearer ${TOKEN}' \
--data-raw '{
  "data":{
    "type":"clearAchPayment",
    "relationships": {
      "payment": {
        "data": {
          "type": "achPayment",
          "id": "10"
        }
      }
    }
  }
}'

This API allows you to immediately clear an existing ACH payment with Clearing status without waiting for the end of the clearing period.

Verb POST
Url https://api.s.unit.sh/sandbox/ach/clear
Data Type clearAchPayment

Relationships

Name Type Description
payment JSON:API Relationship The ACH Payment to be cleared.

Example Response:

{
  "data": {
    "type": "achPayment",
    "id": "10",
    "attributes": {
      "createdAt": "2021-03-09T15:02:01.543Z",
      "amount": 10000,
      "direction": "Debit",
      "description": "Payment from Sandbox",
      "status": "Sent"
    },
    "relationships": {
      "account": {
        "data": {
          "type": "account",
          "id": "10001"
        }
      },
      "customer": {
        "data": {
          "type": "customer",
          "id": "10000"
        }
      }
    }
  }
}

Return ACH payment

Example Request:

curl -X POST 'https://api.s.unit.sh/sandbox/ach/return' \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: Bearer ${TOKEN}' \
--data-raw '{
  "data":{
    "type":"returnAchPayment",
    "relationships": {
      "payment": {
        "data": {
          "type": "achPayment",
          "id": "10"
        }
      }
    }
  }
}'

This API allows you to return an existing ACH payment for testing purposes, the status of payment can either be Clearing or Sent.

Verb POST
Url https://api.s.unit.sh/sandbox/ach/return
Data Type returnAchPayment

Relationships

Name Type Description
payment JSON:API Relationship The ACH Payment to be returned.

Example Response:

{
  "data": {
    "type": "achPayment",
    "id": "10",
    "attributes": {
      "createdAt": "2021-03-09T13:51:51.100Z",
      "amount": 10000,
      "direction": "Debit",
      "description": "Payment from Sandbox",
      "status": "Returned",
      "reason": "R01"
    },
    "relationships": {
      "account": {
        "data": {
          "type": "account",
          "id": "10001"
        }
      },
      "customer": {
        "data": {
          "type": "customer",
          "id": "10000"
        }
      }
    }
  }
}

Receive Wire payment

Example Request:

curl -X POST 'https://api.s.unit.sh/sandbox/payments' \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: Bearer ${TOKEN}' \
--data-raw '{
  "data":{
    "type":"wirePayment",
    "attributes": {
      "amount": 10000,
      "description": "Wire Payment from Sandbox"
    },
    "relationships": {
      "account": {
        "data": {
          "type": "depositAccount",
          "id": "10001"
        }
      }
    }
  }
}'

This API allows you to simulate an incoming wire payment with the specified amount (in cents) for testing purposes.

Verb POST
Url https://api.s.unit.sh/sandbox/wire-payments
Data Type wirePayment

Attributes

Name Type Description
amount integer The amount (in cents).
description string Payment description (maximum of 50 characters).

Relationships

Name Type Description
account JSON:API Relationship The Deposit Account receiving the payment.

Example Response:

{
    "data": {
        "type": "wirePayment",
        "id": "108",
        "attributes": {
            "createdAt": "2021-02-24T11:31:10.009Z",
            "amount": 10000,
            "description": "Wire Payment from Sandbox"
        },
        "relationships": {
            "account": {
                "data": {
                    "type": "depositAccount",
                    "id": "10001"
                }
            },
            "customer": {
                "data": {
                    "type": "customer",
                    "id": "10000"
                }
            }
        }
    }
}

Create Card Authorization

curl -X POST 'https://api.s.unit.sh/sandbox/authorizations' \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: Bearer ${TOKEN}' \
--data-raw '{
  "data":{
    "type":"authorization",
    "attributes": {
      "amount": 2500,
      "cardLast4Digits": "0019",
      "merchantName": "Apple Inc.",
      "merchantType": 1000,
      "merchantLocation": "Cupertino, CA",
      "recurring": false
    },
    "relationships": {
      "account": {
        "data": {
          "type": "depositAccount",
          "id": "10001"
        }
      }
    }
  }
}'

This API allows you to simulate a card purchase authorization with the specified amount (in cents) for testing purposes.

Verb POST
Url https://api.s.unit.sh/sandbox/authorizations
Data Type authorization

Attributes

Name Type Description
amount integer The amount (in cents).
cardLast4Digits string The last 4 digits of the debit card involved in the authorization.
merchantName string The name of the merchant.
merchantType integer The 4-digit ISO 18245 merchant category code (MCC). Use any number (e.g. 1000 for testing).
merchantLocation string Optional. The location (city, state, etc.) of the merchant.
recurring boolean Optional. Default: false. Indicates whether the authorization is recurring

Relationships

Name Type Description
account JSON:API Relationship The Deposit Account of the customer.

Example Response:

{
  "data": {
    "type": "authorization",
    "id": "125",
    "attributes": {
      "createdAt": "2021-03-01T12:41:15.063Z",
      "amount": 2500,
      "cardLast4Digits": "0019",
      "merchant": {
        "name": "Apple Inc.",
        "type": 1000,
        "category": "",
        "location": "Cupertino, CA"
      }
    },
    "relationships": {
      "customer": {
        "data": {
          "type": "customer",
          "id": "10000"
        }
      },
      "account": {
        "data": {
          "type": "account",
          "id": "10001"
        }
      }
    }
  }
}

Create Card Purchase

curl -X POST 'https://api.s.unit.sh/sandbox/purchases' \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: Bearer ${TOKEN}' \
--data-raw '{
  "data":{
    "type":"purchaseTransaction",
    "attributes": {
      "amount": 1000,
      "direction": "Debit",
      "merchantName": "Apple Inc.",
      "merchantType": 1000,
      "merchantLocation": "Cupertino, CA",
      "coordinates": {
        "longitude": -77.0364,
        "latitude": 38.8951
      },
      "last4Digits": "1234",
      "recurring": false
    },
    "relationships": {
      "account": {
        "data": {
          "type": "depositAccount",
          "id": "10000"
        }
      }
    }
  }
}'

This API allows you to simulate a card purchase (or a refund) with the specified amount (in cents) for testing purposes.

Verb POST
Url https://api.s.unit.sh/sandbox/purchases
Data Type purchaseTransaction

Attributes

Name Type Description
amount integer The amount (in cents).
direction string The direction of the purchase- Debit for purchase, Credit for refund.
merchantName string The name of the merchant.
merchantType integer The 4-digit ISO 18245 merchant category code (MCC). Use any number (e.g. 1000 for testing).
merchantLocation string Optional. The location (city, state, etc.) of the merchant.
coordinates Coordinates Optional. Coordinates of the purchase transaction.
last4Digits string The last 4 digits of the debit card involved in the purchase
recurring boolean Optional. Default: false. Indicates whether the transaction is recurring

Relationships

Name Type Description
account JSON:API Relationship The Deposit Account of the customer.
authorization JSON:API Relationship Optional. Simulates a card purchase with a prior Authorization request (see Authorizations). This will cause the authorization to be removed.

Example Response:

{
  "data": {
    "type": "purchaseTransaction",
    "id": "12",
    "attributes": {
      "createdAt": "2020-10-12T21:22:09.528Z",
      "amount": 2500,
      "direction": "Debit",
      "balance": 148490,
      "merchantName": "Apple Inc.",
      "merchantType": 1000,
      "merchantLocation": "Cupertino, CA",
      "coordinates": {
        "longitude": -77.0364,
        "latitude": 38.8951
      },
      "last4Digits": "1234",
      "recurring": false
    },
    "relationships": {
      "account": {
        "data": {
          "type": "depositAccount",
          "id": "10001"
        }
      },
      "customer": {
        "data": {
          "type": "customer",
          "id": "2"
        }
      },
      "card": {
        "data": {
          "type": "card",
          "id": "2"
        }
      }
    }
  }
}

Create Card Purchase Reversal

curl -X POST 'https://api.s.unit.sh/sandbox/reversals' \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: Bearer ${TOKEN}' \
--data-raw '{
  "data":{
    "type":"cardReversalTransaction",
    "attributes": {
      "amount": 2500
    },
    "relationships": {
      "account": {
        "data": {
          "type": "depositAccount",
          "id": "10001"
        }
      },
      "relatedTransaction": {
        "data": {
          "type": "transaction",
          "id": "150"
        }
      }
    }
  }
}'

This API allows you to simulate a Purchase Reversal with the specified amount (in cents) for testing purposes.

Verb POST
Url https://api.s.unit.sh/sandbox/reversals
Data Type cardReversalTransaction

Attributes

Name Type Description
amount integer The amount (in cents).

Relationships

Name Type Description
account JSON:API Relationship The Deposit Account of the customer.
relatedTransaction JSON:API Relationship Optional. The Purchase Transaction which the reversal is related to.

Example Response:

{
  "data": {
    "type": "cardReversalTransaction",
    "id": "165",
    "attributes": {
      "createdAt": "2021-03-08T13:05:45.924Z",
      "amount": 2500,
      "balance": 855500
    },
    "relationships": {
      "account": {
        "data": {
          "type": "depositAccount",
          "id": "10001"
        }
      },
      "customer": {
        "data": {
          "type": "customer",
          "id": "10000"
        }
      },
      "relatedTransaction": {
        "data": {
          "type": "transaction",
          "id": "150"
        }
      }
    }
  }
}

Create ATM Withdrawal

curl -X POST 'https://api.s.unit.sh/sandbox/atm-withdrawals' \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: Bearer ${TOKEN}' \
--data-raw '{
  "data":{
    "type":"atmTransaction",
    "attributes": {
      "amount": 2500,
      "atmName": "HOME FED SAV BK",
      "atmLocation": "Cupertino, CA, US",
      "last4Digits": "1234"
    },
    "relationships": {
      "account": {
        "data": {
          "type": "depositAccount",
          "id": "10001"
        }
      }
    }
  }
}'

This API allows you to simulate an ATM Withdrawal with the specified amount (in cents) for testing purposes.

Verb POST
Url https://api.s.unit.sh/sandbox/atm-withdrawals
Data Type atmTransaction

Attributes

Name Type Description
amount integer The amount (in cents).
atmName string The name of the ATM.
atmLocation string Optional. The location (city, state, etc.) of the ATM.
last4Digits string The last 4 digits of the debit card involved in the withdrawal.

Relationships

Name Type Description
account JSON:API Relationship The Deposit Account of the customer.

Example Response:

{
  "data": {
    "type": "atmTransaction",
    "id": "166",
    "attributes": {
      "createdAt": "2021-03-08T13:18:27.365Z",
      "amount": 2500,
      "balance":855000,
      "atmName": "HOME FED SAV BK",
      "atmLocation": "Cupertino, CA, US",
      "last4Digits": "1234"
    },
    "relationships": {
      "account": {
        "data": {
          "type": "depositAccount",
          "id": "10001"
        }
      },
      "customer": {
        "data": {
          "type": "customer",
          "id": "10000"
        }
      },
      "card": {
        "data": {
          "type": "card",
          "id": "2"
        }
      }
    }
  }
}

Activate Card

Example Request:

curl -X POST 'https://api.s.unit.sh/sandbox/cards/9/activate' \
-H "Authorization: Bearer ${TOKEN}"

Activate a card.

Verb POST
Url https://api.s.unit.sh/sandbox/cards/{cardId}/activate

Generate Account Statement

Example Request:

curl -X POST 'https://api.s.unit.sh/sandbox/accounts/10001/generate-statement' \
-H "Authorization: Bearer ${TOKEN}"

Generate an account statement. The statement includes any transactions performed between the beginning of the current month and up until EOD yesterday.

Verb POST
Url https://api.s.unit.sh/sandbox/accounts/{accountId}/generate-statement

Create Customer Token Without 2FA

Example Request:

curl -X POST 'https://api.s.unit.sh/customers/<CUSTOMER_TOKEN>/token' \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: Bearer ${TOKEN}' \
--data-raw '{
  "data":{
    "type":"customerToken",
    "attributes": {
      "scope": "customers accounts payments payments-create counterparties counterparties-create cards-create",
      "verificationCode": "000001"
    }
  }
}
'

Usually in order to obtain a customer token with write permission we need to perform the following actions:

For simulation purposes we can skip the 2FA requirement by calling only Create Customer Token passing "verificationCode": "000001".

Statements

An account statement is a list of all transactions for an account over a monthly period. The statement includes deposits, charges, withdrawals, as well as the starting and ending balance for the period.

The account statement API enables customers to track their spending, identify fraudulent activity and save money by tracking the fees they pay.

Unit provides white-labeled HTML based account statements supporting all browsers and standard screen resolutions.

List

List statement resources. Filtering and paging can be applied.

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

Query Parameters

Name Type Default Description
page[limit] integer 100 Maximum number of resources that will be returned. Maximum is 1000 resources. See Pagination.
page[offset] integer 0 Number of resources to skip. See Pagination.
filter[accountId] string (empty) Optional. Filters the results by the specified account id.
filter[customerId] string (empty) Optional. Filters the results by the specified customer id.

Response

Example Response:

{
  "data": [
    {
      "type": "statement",
      "id": "1",
      "attributes": {
        "period": "2020-07"
      },
      "relationships": {
        "account": {
          "data": {
            "type": "account",
            "id": "1000"
          }
        },
        "customer": {
          "data": {
            "type": "customer",
            "id": "1"
          }
        }
      }
    },
    {
      "type": "statement",
      "id": "2",
      "attributes": {
        "period": "2020-08"
      },
      "relationships": {
        "account": {
          "data": {
            "type": "account",
            "id": "1000"
          }
        },
        "customer": {
          "data": {
            "type": "customer",
            "id": "1"
          }
        }
      }
    }
  ]
}

Response is a JSON:API document.

200 OK

Field Type Description
data Array of Statement Array of statement resources.

Get HTML by Id

Get a statement HTML output by id.

curl -X GET 'https://api.s.unit.sh/statements/1/html' \
-H "Authorization: Bearer ${TOKEN}"
Verb GET
Url https://api.s.unit.sh/statements/{id}/html
Required Scope statements

Query Parameters

Name Type Default Description
filter[customerId] string (empty) Optional. Verify that the statements belongs to the customer.

Response

Response is a HTML document.

Events

Unit uses Events to record important changes happening under your org. Once an event is created, it will be delivered to your application via a webhook call.

Our event types follow a specific structure: resource.event.

Each event includes an id field, which uniquely identifies the event instance, and a type field that identifies the type of the event instance.

Each event type includes a different set of attributes and relationships, relevant to that specific event.

account.closed

Example account.closed payload:

{
  "data": [
    {
      "id": "269",
      "type": "account.closed",
      "attributes": {
        "createdAt": "2021-04-13T07:40:43.813Z",
        "closeReason": "ByCustomer"
      },
      "relationships": {
        "account": {
          "data": {
            "id": "10004",
            "type": "account"
          }
        },
        "customer": {
          "data": {
            "id": "10000",
            "type": "customer"
          }
        }
      }
    }
  ]
}

Occurs when a Deposit Account is closed.

application.denied

Example application.created payload:

{
  "data": [
    {
      "id": "28",
      "type": "application.denied",
      "attributes": {
        "createdAt": "2020-07-29T12:53:05.882Z"
      },
      "relationships": {        
        "application": {
          "data": {
            "id": "52",
            "type": "individualApplication"
          }
        }
      }
    }
  ]
}

Occurs when an Application is denied.

application.awaitingDocuments

Example application.awaitingDocuments payload:

{
  "data": [
    {
      "id": "3000",
      "type": "application.awaitingDocuments",
      "attributes": {
        "createdAt": "2020-07-29T12:53:05.882Z"
      },
      "relationships": {        
        "application": {
          "data": {
            "id": "87",
            "type": "individualApplication"
          }
        }
      }
    }
  ]
}

Occurs when additional Application Documents are required to approve an Application.

authorization.created

Example authorization.created payload:

{
  "data": [
    {
      "id": "83",
      "type": "authorization.created",
      "attributes": {
        "createdAt": "2021-02-21T07:31:18.692Z",
        "cardLast4Digits": "0019",
        "recurring": false
      },
      "relationships": {
        "authorization": {
          "data": {
            "id": "98",
            "type": "authorization"
          }
        },
        "account": {
          "data": {
            "id": "10001",
            "type": "account"
          }
        },
        "customer": {
          "data": {
            "id": "10000",
            "type": "customer"
          }
        }
      }
    }
  ]
}

Occurs when an Authorization is created.

card.activated

Example card.activated payload:

{
  "data": [
    {
      "id": "73",
      "type": "card.activated",
      "attributes": {
        "createdAt": "2021-02-15T09:23:47.778Z"
      },
      "relationships": {
        "card": {
          "data": {
            "id": "6",
            "type": "individualDebitCard"
          }
        },
        "account": {
          "data": {
            "id": "10001",
            "type": "account"
          }
        },
        "customer": {
          "data": {
            "id": "10000",
            "type": "customer"
          }
        }
      }
    }
  ]
}

Occurs when a Card is activated for the first time.

card.statusChanged

Example card.statusChanged payload:

{
  "data": [
    {
      "id": "74",
      "type": "card.statusChanged",
      "attributes": {
        "createdAt": "2021-02-22T09:23:47.778Z",
        "newStatus": "Lost",
        "previousStatus": "Active"
      },
      "relationships": {
        "card": {
          "data": {
            "id": "6",
            "type": "individualDebitCard"
          }
        },
        "account": {
          "data": {
            "id": "10001",
            "type": "account"
          }
        },
        "customer": {
          "data": {
            "id": "10000",
            "type": "customer"
          }
        }
      }
    }
  ]
}

Occurs when a Card status changes, excluding first time card activation (see card.activated).

customer.created

Example customer.created payload:

{
  "data": [
    {
      "id": "28",
      "type": "customer.created",
      "attributes": {
        "createdAt": "2020-07-29T12:53:05.882Z"
      },
      "relationships": {
        "customer": {
          "data": {
            "id": "52",
            "type": "individualCustomer"
          }
        },
        "application": {
          "data": {
            "id": "52",
            "type": "individualApplication"
          }
        }
      }
    }
  ]
}

Occurs when a new Customer is created.

document.approved

Example document.approved payload:

{
  "data": [
    {
      "id": "193",
      "type": "document.approved",
      "attributes": {
        "createdAt": "2020-11-09T09:05:49.999Z"
      },
      "relationships": {
        "document": {
          "data": {
            "id": "6",
            "type": "document"
          }
        },
        "application": {
          "data": {
            "id": "10009",
            "type": "individualApplication"
          }
        }
      }
    }
  ]
}

Occurs when an Application Document is approved.

document.rejected

Example document.rejected payload:

{
  "data": [
    {
      "id": "190",
      "type": "document.rejected",
      "attributes": {
        "reason": "blurry image",
        "reasonCode": "PoorQuality",
        "createdAt": "2020-11-08T18:34:38.533Z"
      },
      "relationships": {
        "document": {
          "data": {
            "id": "6",
            "type": "document"
          }
        },
        "application": {
          "data": {
            "id": "10009",
            "type": "individualApplication"
          }
        }
      }
    }
  ]
}

Occurs when an Application Document is rejected.

payment.clearing

Example payment.clearing payload:

{
  "data": [
    {
      "id": "290",
      "type": "payment.clearing",
      "attributes": {
        "previousStatus": "Pending",
        "createdAt": "2020-11-08T18:34:38.533Z"
      },
      "relationships": {
        "payment": {
          "data": {
            "id": "6",
            "type": "payment"
          }
        },
        "account": {
          "data": {
            "id": "10009",
            "type": "account"
          }
        },
        "customer": {
          "data": {
            "id": "10002",
            "type": "customer"
          }
        }
      }
    }
  ]
}

Occurs when an originated Debit ACH Payment was delivered to the ACH network, but the account was not credited yet.

payment.sent

Example payment.sent payload:

{
  "data": [
    {
      "id": "291",
      "type": "payment.sent",
      "attributes": {
        "previousStatus": "Pending",
        "createdAt": "2020-11-08T18:34:38.533Z"
      },
      "relationships": {
        "payment": {
          "data": {
            "id": "8",
            "type": "payment"
          }
        },
        "account": {
          "data": {
            "id": "10009",
            "type": "account"
          }
        },
        "customer": {
          "data": {
            "id": "10002",
            "type": "customer"
          }
        }
      }
    }
  ]
}

Occurs when an originated ACH Payment was processed by the ACH network.

payment.returned

Example payment.returned payload:

{
  "data": [
    {
      "id": "295",
      "type": "payment.returned",
      "attributes": {
        "previousStatus": "Sent",
        "createdAt": "2021-01-02T13:38:28.223Z"
      },
      "relationships": {
        "payment": {
          "data": {
            "id": "10",
            "type": "payment"
          }
        },
        "account": {
          "data": {
            "id": "10009",
            "type": "account"
          }
        },
        "customer": {
          "data": {
            "id": "10002",
            "type": "customer"
          }
        }
      }
    }
  ]
}

Occurs when a sent ACH Payment was returned by the ACH network or the receiving bank.

statements.created

Example statements.created payload:

{
  "data": [
    {
      "id": "241",
      "type": "statements.created",
      "attributes": {
        "createdAt": "2021-03-01T00:16:28.911Z",
        "period": "2021-02"
      }
    }
  ]
}

Occurs when all Statements were created for the previous month.

transaction.created

Example transaction.created payload:

{
  "data": [
    {
      "id": "34",
      "type": "transaction.created",
      "attributes": {
        "summary": "Funding",
        "direction": "Debit",        
        "amount": "2500",
        "createdAt": "2020-07-30T09:17:21.593Z"
      },
      "relationships": {
        "transaction": {
          "data": {
            "type": "receivedAch",
            "id": "10001" 
          }   
        },
        "account": {
          "data": {
            "id": "1000",
            "type": "account"
          }
        },
        "customer": {
          "data": {
            "id": "1",
            "type": "customer"
          }
        },
        "payment": {
          "data": {
            "id": "515",
            "type": "payment"
          }
        }
      }
    }
  ]
}

Occurs when a Transaction is created.

List

List event resources. Paging can be applied.

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

Query Parameters

Name Type Default Description
page[limit] integer 100 Maximum number of resources that will be returned. Maximum is 1000 resources. See Pagination.
page[offset] integer 0 Number of resources to skip. See Pagination.

Response

Example Response:

{
  "data": [
    {
      "id": "231",
      "type": "customer.created",
      "attributes": {
        "createdAt": "2021-03-15T12:20:39.216Z"
      },
      "relationships": {
        "customer": {
          "data": {
            "id": "10004",
            "type": "businessCustomer"
          }
        }
      }
    },
    {
      "id": "230",
      "type": "transaction.created",
      "attributes": {
        "createdAt": "2021-03-15T07:49:09.089Z",
        "amount": 10000,
        "direction": "Credit",
        "summary": "Wire from Sender"
      },
      "relationships": {
        "account": {
          "data": {
            "id": "10005",
            "type": "account"
          }
        },
        "transaction": {
          "data": {
            "id": "189",
            "type": "wireTransaction"
          }
        },
        "customer": {
          "data": {
            "id": "10000",
            "type": "individualCustomer"
          }
        }
      }
    }
  ]
}

Response is a JSON:API document.

200 OK

Field Type Description
data Array of Event Array of event resources.

Fire Event

Example Request:

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

Resend a previously published webhook event.

Verb POST
Url https://api.s.unit.sh/events/{eventId}

Resources

IndividualApplication

Example IndividualApplication resource:

{
  "type": "individualApplication",
  "id": "53",
  "attributes": {
    "createdAt": "2020-01-14T14:05:04.718Z",
    "fullName": {
      "first": "Peter",
      "last": "Parker"
    },
    "ssn": "721074426",
    "address": {
      "street": "20 Ingram St",
      "street2": null,
      "city": "Forest Hills",
      "state": "NY",
      "postalCode": "11375",
      "country": "US"
    },
    "dateOfBirth": "2001-08-10",
    "email": "peter@oscorp.com",
    "phone": {
      "countryCode": "1",
      "number": "1555555578"
    },
    "status": "AwaitingDocuments",
    "message": "Waiting for you to upload the required documents.",
    "evaluationOutcome": "Approved",
    "tags": {
      "userId": "106a75e9-de77-4e25-9561-faffe59d7814"
    }
  },
  "relationships": {
    "org": {
      "data": {
        "type": "org",
        "id": "1"
      }
    },
    "documents": {
      "data": [
        {
          "type": "document",
          "id": "1"
        },
        {
          "type": "document",
          "id": "2"
        }
      ]
    }
  }
}

IndividualApplication is a JSON:API resource, top-level fields:

Field type Description
id string Identifier of the application resource.
type string Type of the application resource. For individual application the value is always individualApplication.
attributes JSON Object JSON object representing the application data.
relationships JSON:API Relationships Describes relationships between the application resource and other resources (documents).

Attributes

Field type Description
status string One of AwaitingDocuments, PendingReview, Approved or Denied, see Application Statuses.
message string A message describing the IndividualApplication status.
createdAt RFC3339 Date string The date the resource was created.
ssn string SSN of the individual (numbers only). Either ssn or passport will be populated.
passport string Individual passport number. Either ssn or passport will be populated.
nationality ISO31661-Alpha2 string Only when Passport is populated. Two letters representing the individual nationality (e.g. "US").
fullName FullName Full name of the individual.
dateOfBirth RFC3339 Date string Date only (e.g. "2001-08-15").
address Address Address of the individual.
phone Phone Phone of the individual.
email string Email address of the individual.
ip string IP address of the end-customer creating the application, if specified.
soleProprietorship boolean Optional. Indicates whether the individual is a sole proprietor, if specified.
ein string Optional. Indicates if the individual is a sole proprietor who has an Employer Identification Number, if specified.
dba string Optional. Indicates if the individual is a sole proprietor who is doing business under a different name, if specified.
tags object See Tags.

Relationships

Field type Description
documents Array of JSON:API Relationship Application's documents.
customer JSON:API Relationship Optional. The created Customer in case of approved application.

BusinessApplication

Example BusinessApplication resource:

{
  "type": "businessApplication",
  "id": "50",
  "attributes": {
    "createdAt": "2020-01-13T16:01:19.346Z",
    "name": "Pied Piper",
    "dba": null,
    "address": {
      "street": "5230 Newell Rd",
      "street2": null,
      "city": "Palo Alto",
      "state": "CA",
      "postalCode": "94303",
      "country": "US"
    },
    "phone": {
      "countryCode": "1",
      "number": "1555555578"
    },
    "stateOfIncorporation": "DE",
    "ein": "123456789",
    "entityType": "Corporation",
    "contact": {
      "fullName": {
        "first": "Richard",
        "last": "Hendricks"
      },
      "email": "richard@piedpiper.com",
      "phone": {
        "countryCode": "1",
        "number": "1555555578"
      }
    },
    "officer": {
      "fullName": {
        "first": "Richard",
        "last": "Hendricks"
      },
      "ssn": "123456789",
      "address": {
        "street": "5230 Newell Rd",
        "street2": null,
        "city": "Palo Alto",
        "state": "CA",
        "postalCode": "94303",
        "country": "US"
      },
      "dateOfBirth": "2001-08-10",
      "email": "richard@piedpiper.com",
      "phone": {
        "countryCode": "1",
        "number": "1555555589"
      },
      "status": "Approved"
    },
    "beneficialOwners": [
      {
        "fullName": {
          "first": "Richard",
          "last": "Hendricks"
        },
        "ssn": "123456789",
        "address": {
          "street": "5230 Newell Rd",
          "street2": null,
          "city": "Palo Alto",
          "state": "CA",
          "postalCode": "94303",
          "country": "US"
        },
        "dateOfBirth": "2001-08-10",
        "phone": {
          "countryCode": "1",
          "number": "1555555589"
        },
        "email": "richard@piedpiper.com",
        "status": "Approved"
      }
    ],
    "tags": {
      "userId": "106a75e9-de77-4e25-9561-faffe59d7814"
    },
    "status": "AwaitingDocuments",
    "message": "Waiting for you to upload the required documents.",
    "evaluationOutcome": "Approved"
  },
  "relationships": {
    "org": {
      "data": {
        "type": "org",
        "id": "1"
      }
    },
    "documents": {
      "data": [
        {
          "type": "document",
          "id": "1"
        },
        {
          "type": "document",
          "id": "2"
        },
        {
          "type": "document",
          "id": "3"
        }
      ]
    }
  }
}

BusinessApplication is a JSON:API resource, top-level fields:

Field type Description
id string Identifier of the application resource.
type string Type of the application resource, for business application the value is always businessApplication.
attributes JSON Object JSON object representing the application data.
relationships JSON:API Relationships Describes relationships between the application resource and other resources (documents).

Attributes

Field type Description
status string One of AwaitingDocuments, PendingReview, Approved or Denied, see Application Statuses.
message string A message describing the BusinessApplication status.
createdAt RFC3339 Date string The date the resource was created.
name string Name of the business.
dba string Optional. “Doing business as”.
address Address Address of the business.
phone Phone Phone of the business.
stateOfIncorporation string Two letters representing a US state.
ein string Business EIN (numbers only).
entityType string One of "Corporation", "LLC" or "Partnership".
contact BusinessContact Primary contact of the business.
officer Officer Officer representing the business, must be CEO, CFO, President or BenefitsAdministrationOfficer. The officer would need to go over KYC process and provide documents.
beneficialOwners Array of BeneficialOwner Array of beneficial owners of the business. Beneficial Owner is anyone with more than 25% ownership. Beneficial Owners would need to go over KYC process and provide documents.
tags object See Tags.

Relationships

Field type Description
documents Array of JSON:API Relationship Application's documents.
customer JSON:API Relationship Optional. The created Customer in case of approved application.

ApplicationDocument

Example ApplicationDocument resource:

{
    "type": "document",
    "id": "3",
    "attributes": {
        "documentType": "IdDocument",
        "status": "Approved",
        "description": "Please provide a copy of your unexpired government issued photo ID which would include Drivers License or State ID.",
        "name": "Richard Hendricks",
        "dateOfBirth": "2001-08-15"
    }
}

ApplicationDocument is a JSON:API resource, top-level fields:

Field type Description
id string Identifier of the document resource.
type string Always document.
attributes JSON Object JSON object representing the document’s data.

Attributes

Field type Description
status string One of Required, ReceivedBack, ReceivedFront, Invalid, Approved or PendingReview, see Application Document Status.
documentType string One of IdDocument, Passport, AddressVerification, CertificateOfIncorporation or EmployerIdentificationNumberConfirmation.
description string The document requirements description.
name string Name of business or individual.
address Address Individual address, present only for the AddressVerification document type.
dateOfBirth RFC3339 Date string Date only (e.g. "2001-08-15"). Present only for Passport and License document types.
passport string Individual passport number. Present only for the Passport document type.
ein string Business EIN. Present only for the EmployerIdentificationNumberConfirmation document type.
reasonCode string Application Document rejection reason code. Present only when document status is Invalid. One of PoorQuality, NameMismatch, SSNMismatch, AddressMismatch, DOBMismatch, ExpiredId, EINMismatch, StateMismatch, Other.
reason string Application Document rejection reason. Present only when document status is Invalid.

IndividualCustomer

Example IndividualCustomer resource:

{
  "type": "individualCustomer",
  "id": "8",
  "attributes": {
    "createdAt": "2020-05-12T19:41:04.123Z",
    "fullName": {
      "first": "Peter",
      "last": "Parker"
    },
    "ssn": "721074426",
    "address": {
      "street": "20 Ingram St",
      "street2": null,
      "city": "Forest Hills",
      "state": "NY",
      "postalCode": "11375",
      "country": "US"
    },
    "dateOfBirth": "2001-08-10",
    "email": "peter@oscorp.com",
    "phone": {
      "countryCode": "1",
      "number": "1555555578"
    },
    "tags": {
      "userId": "106a75e9-de77-4e25-9561-faffe59d7814"
    },
    "riskRate": "low"
  },
  "relationships": {
    "org": {
      "data": {
        "type": "org",
        "id": "1"
      }
    },
    "application": {
      "data": {
        "type": "individualApplication",
        "id": "8"
      }
    }
  }
}

IndividualCustomer is a JSON:API resource, describing the individual customer. Top-level fields:

Field type Description
id string Identifier of the individual resource.
type string Type of the resource, the value is always individualCustomer.
attributes JSON Object JSON object representing the individual data.
relationships JSON:API Relationships Describes relationships between the customer resource, the Org it belongs to, and the Application it was created by.
Field type Description
createdAt RFC3339 Date string The date the resource was created.
ssn string Individual passport number. Either ssn or passport will be populated.
passport string Individual passport number. Either ssn or passport will be populated.
nationality ISO31661-Alpha2 string Only when Passport is populated. Two letters representing the individual nationality (e.g. "US").
fullName FullName Full name of the individual.
dateOfBirth RFC3339 Date string Date only (e.g. "2001-08-15").
address Address Address of the individual.
phone Phone Phone of the individual.
email string Email address of the individual.
tags object See Tags.

Relationships

Name Type Description
org JSON:API Relationship The Org of the individual.
application JSON:API Relationship The Application that created this individual.

BusinessCustomer

Example BusinessCustomer resource:

{
  "type": "businessCustomer",
  "id": "1",
  "attributes": {
    "createdAt": "2020-05-10T12:28:37.698Z",
    "name": "Pied Piper",
    "address": {
      "street": "5230 Newell Rd",
      "street2": null,
      "city": "Palo Alto",
      "state": "CA",
      "postalCode": "94303",
      "country": "US"
    },
    "phone": {
      "countryCode": "1",
      "number": "1555555578"
    },
    "stateOfIncorporation": "DE",
    "ein": "123456789",
    "entityType": "Corporation",
    "contact": {
      "fullName": {
        "first": "Richard",
        "last": "Hendricks"
      },
      "email": "richard@piedpiper.com",
      "phone": {
        "countryCode": "1",
        "number": "1555555578"
      }
    },
    "tags": {
      "userId": "106a75e9-de77-4e25-9561-faffe59d7814"
    },
    "riskRate": "low"
  },
  "relationships": {
    "org": {
      "data": {
        "type": "org",
        "id": "1"
      }
    },
    "application": {
      "data": {
        "type": "businessApplication",
        "id": "1"
      }
    }
  }
}

BusinessCustomer is a JSON:API resource, describing the business customer. Top-level fields:

Field type Description
id string Identifier of the business resource.
type string Type of the resource, the value is always businessCustomer.
attributes JSON Object JSON object representing the business data.
relationships JSON:API Relationships Describes relationships between the customer resource, the Org it belongs to, and the Application it was created by.

Attributes

Field type Description
createdAt RFC3339 Date string The date the resource was created.
name string Name of the business.
dba string Optional. “Doing business as”.
address Address Address of the business.
phone Phone Phone of the business.
stateOfIncorporation string Two letters representing a US state.
ein string Business EIN (numbers only).
entityType string One of "Corporation" or "LLC".
contact BusinessContact Primary contact of the business.
tags object See Tags. Inherited from the application tags (see Tag Inheritance).

Relationships

Name Type Description
org JSON:API Relationship The Org of the business.
application JSON:API Relationship The Application that created this business.

DepositAccount

Example DepositAccount Resource:

{
  "type": "depositAccount",
  "id": "1",
  "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"
      }
    }
  }
}

DepositAccount is a JSON:API resource, top-level fields:

Field type Description
id string Identifier of the deposit account resource.
type string Type of the resource, the value is always depositAccount.
attributes JSON Object JSON object representing the deposit account data.
relationships JSON:API Relationships Describes relationships between the deposit account resource and the customer.

Attributes

Name Type Description
createdAt RFC3339 Date string The date the resource was created.
name string Name of the account holder.
depositProduct string The name of the deposit product.
routingNumber string Routing number of account.
accountNumber string Account number, together with the routingNumber forms the identifier of the account on the ACH network.
currency string Currency of the account.
balance integer The balance amount (in cents).
hold integer The hold amount (in cents).
available integer The available balance for spending (in cents).
tags object See Tags.
status string Status of the account, either Open or Closed.

Note: the currency is currently always set to USD. The balance is represented in cents.

Relationships

Name Type Description
customer JSON:API Relationship The customer.

IndividualDebitCard

Example IndividualDebitCard resource:

{
  "type": "individualDebitCard",
  "id": "8",
  "attributes": {
    "createdAt": "2020-05-13T09:07:47.645Z",
    "last4Digits": "1234",
    "expirationDate": "2022-05",
    "shippingAddress": {
      "street": "5230 Newell Rd",
      "street2": null,
      "city": "Palo Alto",
      "state": "CA",
      "postalCode": "94303",
      "country": "US"
    },
    "status": "Active"
  },
  "relationships": {
    "account": {
      "data": {
        "type": "depositAccount",
        "id": "2"
      }
    },
    "customer": {
      "data": {
        "type": "individualCustomer",
        "id": "2"
      }
    }
  }
}

IndividualDebitCard is a JSON:API resource, top-level fields:

Field type Description
id string Identifier of the card resource.
type string Type of the card resource. For individual debit card the value is always individualDebitCard.
attributes JSON Object JSON object representing the card data.
relationships JSON:API Relationships Describes relationships between the card resource and other resources (account and customer).

Attributes

Field type Description
createdAt RFC3339 Date string The date the resource was created.
last4Digits string Last 4 digits of the debit card.
expirationDate string Card expiration date, formatted YYYY-MM, e.g "2020-05".
shippingAddress Address Optional. Shipping address, if specified.
status string Status of the card, one of: Active, Inactive, Stolen, Lost, Frozen, ClosedByCustomer, SuspectedFraud.
design string Optional. Card design, if specified.

Relationships

Field type Description
account JSON:API Relationship The account the card belongs to.
customer JSON:API Relationship The individual or business customer the card belongs to.

BusinessDebitCard

Example BusinessDebitCard resource:

{
  "type": "businessDebitCard",
  "id": "9",
  "attributes": {
    "createdAt": "2020-05-13T09:42:21.857Z",
    "last4Digits": "2074",
    "expirationDate": "2022-05",
    "shippingAddress": {
      "street": "5230 Newell Rd",
      "street2": null,
      "city": "Palo Alto",
      "state": "CA",
      "postalCode": "94303",
      "country": "US"
    },
    "address": {
      "street": "5230 Newell Rd",
      "street2": null,
      "city": "Palo Alto",
      "state": "CA",
      "postalCode": "94303",
      "country": "US"
    },
    "fullName": {
      "first": "Richard",
      "last": "Hendricks"
    },
    "phone": {
      "countryCode": "1",
      "number": "1555555578"
    },
    "email": "richard@piedpiper.com",
    "dateOfBirth": "2001-08-10",
    "ssn": "123456789",
    "status": "Active"
  },
  "relationships": {
    "account": {
      "data": {
        "type": "depositAccount",
        "id": "1"
      }
    },
    "customer": {
      "data": {
        "type": "businessCustomer",
        "id": "1"
      }
    }
  }
}

BusinessDebitCard is a JSON:API resource, top-level fields:

Field type Description
id string Identifier of the card resource.
type string Type of the card resource. For business debit card the value is always BusinessDebitCard.
attributes JSON Object JSON object representing the card data.
relationships JSON:API Relationships Describes relationships between the card resource and other resources (account and customer).

Attributes

Field type Description
createdAt RFC3339 Date string The date the resource was created.
last4Digits string Last 4 digits of the debit card.
expirationDate string Card expiration date, formatted YYYY-MM, e.g "2020-05".
shippingAddress Address Optional. Shipping address, if specified.
ssn string SSN of the card holder (numbers only). Either an SSN or a passport number is required.
passport string Passport number of the card holder. Either an SSN or a passport is required.
nationality ISO31661-Alpha2 string Only when Passport is populated. Two letters representing the card holder nationality. (e.g. “US”).
fullName FullName Full name of the card holder.
dateOfBirth RFC3339 Date string Date of birth of the card holder (e.g. "2001-08-15").
address Address Address of the card holder.
phone Phone Phone of the card holder.
email string Email address of the card holder.
status string Status of the card, one of: Active, Inactive, Stolen, Lost, Frozen, ClosedByCustomer, SuspectedFraud.
design string Optional. Card design, if specified.

Relationships

Field type Description
account JSON:API Relationship Account the card belong to.
customer JSON:API Relationship Holder of the account.

IndividualVirtualDebitCard

Example IndividualVirtualDebitCard resource:

{
  "type": "individualVirtualDebitCard",
  "id": "8",
  "attributes": {
    "createdAt": "2020-05-13T09:07:47.645Z",
    "last4Digits": "1234",
    "expirationDate": "2022-05",
    "status": "Active"
  },
  "relationships": {
    "account": {
      "data": {
        "type": "depositAccount",
        "id": "2"
      }
    },
    "customer": {
      "data": {
        "type": "individualCustomer",
        "id": "2"
      }
    }
  }
}

IndividualVirtualDebitCard is a JSON:API resource, top-level fields:

Field type Description
id string Identifier of the card resource.
type string Type of the card resource. For individual virtual debit card the value is always individualVirtualDebitCard.
attributes JSON Object JSON object representing the card data.
relationships JSON:API Relationships Describes relationships between the card resource and other resources (account and customer).

Attributes

Field type Description
createdAt RFC3339 Date string The date the resource was created.
last4Digits string Last 4 digits of the debit card.
expirationDate string Card expiration date, formatted YYYY-MM, e.g "2020-05".
status string Status of the card, one of: Active, Inactive, Stolen, Lost, Frozen, ClosedByCustomer, SuspectedFraud.

Relationships

Field type Description
account JSON:API Relationship The account the card belongs to.
customer JSON:API Relationship The individual or business customer the card belongs to.

BusinessVirtualDebitCard

Example BusinessVirtualDebitCard resource:

{
  "type": "businessVirtualDebitCard",
  "id": "9",
  "attributes": {
    "createdAt": "2020-05-13T09:42:21.857Z",
    "last4Digits": "2074",
    "expirationDate": "2022-05",
    "address": {
      "street": "5230 Newell Rd",
      "street2": null,
      "city": "Palo Alto",
      "state": "CA",
      "postalCode": "94303",
      "country": "US"
    },
    "fullName": {
      "first": "Richard",
      "last": "Hendricks"
    },
    "phone": {
      "countryCode": "1",
      "number": "1555555578"
    },
    "email": "richard@piedpiper.com",
    "dateOfBirth": "2001-08-10",
    "ssn": "123456789",
    "status": "Active"
  },
  "relationships": {
    "account": {
      "data": {
        "type": "depositAccount",
        "id": "1"
      }
    },
    "customer": {
      "data": {
        "type": "businessCustomer",
        "id": "1"
      }
    }
  }
}

BusinessVirtualDebitCard is a JSON:API resource, top-level fields:

Field type Description
id string Identifier of the card resource.
type string Type of the card resource. For business virtual debit card the value is always businessVirtualDebitCard.
attributes JSON Object JSON object representing the card data.
relationships JSON:API Relationships Describes relationships between the card resource and other resources (account and customer).

Attributes

Field type Description
createdAt RFC3339 Date string The date the resource was created.
last4Digits string Last 4 digits of the debit card.
expirationDate string Card expiration date, formatted YYYY-MM, e.g "2020-05".
ssn string SSN of the card holder (numbers only). Either an SSN or a passport number is required.
passport string Passport number of the card holder. Either an SSN or a passport is required.
nationality ISO31661-Alpha2 string Only when Passport is populated. Two letters representing the card holder nationality. (e.g. “US”).
fullName FullName Full name of the card holder.
dateOfBirth RFC3339 Date string Date of birth of the card holder (e.g. "2001-08-15").
address Address Address of the card holder.
phone Phone Phone of the card holder.
email string Email address of the card holder.
status string Status of the card, one of: Active, Inactive, Stolen, Lost, Frozen, ClosedByCustomer, SuspectedFraud.

Relationships

Field type Description
account JSON:API Relationship Account the card belong to.
customer JSON:API Relationship Holder of the account.

ACH Counterparty

Example Payment resource:

{
  "type": "achCounterparty",
  "id": "8",
  "attributes": {
    "createdAt": "2020-05-13T09:07:47.645Z",
    "name": "Joe Doe",
    "routingNumber": "011000138",
    "bank": "Bank Of America",
    "accountNumber": "123",
    "accountType": "Checking",
    "type": "Person",
    "permissions": "CreditOnly"
  },
  "relationships": {
    "customer": {
      "data": {
        "type": "customer",
        "id": "111111"
      }
    }
  }
}

Counterparty is a JSON:API resource, top-level fields:

Field type Description
id string Identifier of the ACH counterparty resource.
type string Type of the ACH counterparty resource.
attributes JSON Object JSON object representing the payment resource.
relationships JSON:API Relationships Describes relationships between the ACH counterparty and the originating customer.

Attributes

Name Type Description
createdAt RFC3339 Date string The date the resource was created.
name string The account holder's name (whether an individual or a business).
routingNumber string Valid 9-digit ABA routing transit number.
bank string Name of the bank.
accountNumber string Bank account number.
accountType string Either Checking or Savings.
type string Either Business, Person or Unknown.
permissions string Either CreditOnly or CreditAndDebit.

Relationships

Name Type Description
customer JSON:API Relationship The customer the counterparty belongs to.

ACH Payment

Example AchPayment resource:

{
  "data": {
    "type": "achPayment",
    "id": "50",
    "attributes": {
      "createdAt": "2020-01-13T16:01:19.346Z",
      "status": "Pending",
      "counterparty": {
        "routingNumber": "812345678",
        "accountNumber": "12345569",
        "accountType": "Checking",
        "name": "Jane Doe"
      },
      "description": "Funding",
      "direction": "Credit",
      "amount": 10000
    },
    "relationships": {
      "account": {
        "data": {
          "type": "depositAccount",
          "id": "555"
        }
      },
      "customer": {
        "data": {
          "type": "individualCustomer",
          "id": "99823"
        }
      },
      "counterparty": {
        "data": {
          "type": "counterparty",
          "id": "4567"
        }
      },
      "transaction": {
        "data": {
          "type": "transaction",
          "id" : "4003"
        }
      }
    }
  }
}

AchPayment is a JSON:API resource, top-level fields:

Field type Description
id string Identifier of the ACH payment resource.
type string Type of the payment resource. For originations the value is achPayment.
attributes JSON Object JSON object representing the payment resource.
relationships JSON:API Relationships Describes relationships between the ACH payment and the originating deposit account and customer.

Attributes

Name Type Description
createdAt RFC3339 Date string The date the resource was created.
status string One of Pending, Rejected, Clearing, Sent, Canceled, Returned. See ACH Status.
reason string (Optional) More information about the status.
counterparty Counterparty The party on the other side of the ACH payment.
direction string The direction in which the funds flow (either Debit or Credit).
description string Payment description (maximum of 10 characters), also known as Company Entry Description, this will show up on statement of the counterparty.
addenda string Optional, additional payment description (maximum of 50 characters), not all institutions present that.
amount string The amount (cents) of the payment.
tags object See Tags.

Relationships

Name Type Description
account JSON:API Relationship The Deposit Account originating the transfer.
customer JSON:API Relationship The Customer the deposit account belongs to. The customer is either a business or a individual.
counterparty JSON:API Relationship The Counterparty the payment to be made to.

Book Payment

Example BookPayment resource:

{
  "data": {
    "type": "bookPayment",
    "id": "1232",
    "attributes": {
      "createdAt": "2021-02-21T13:03:19.025Z",
      "amount": 1500,
      "direction": "Credit",
      "description": "Funding",
      "status": "Sent"
    },
    "relationships": {
      "account": {
        "data": {
          "type": "account",
          "id": "555"
        }
      },
      "customer": {
        "data": {
          "type": "customer",
          "id": "10000"
        }
      },
      "counterpartyAccount": {
        "data": {
          "type": "account",
          "id": "99821"
        }
      },
      "counterpartyCustomer": {
        "data": {
          "type": "customer",
          "id": "10000"
        }
      },
      "transaction": {
        "data": {
          "type": "transaction",
          "id": "1413"
        }
      }
    }
  }
}

BookPayment is a JSON:API resource, top-level fields:

Field type Description
id string Identifier of the book payment resource.
type string Type of the payment resource. The value is always bookPayment.
attributes JSON Object JSON object representing the payment resource.
relationships JSON:API Relationships Describes relationships between the ACH payment and the originating deposit account and customer.

Attributes

Name Type Description
createdAt RFC3339 Date string The date the resource was created.
status string Either Sent or Rejected (see reason for details).
reason string (Optional) More information about the status.
direction string The direction in which the funds flow (either Debit or Credit).
description string Payment description (maximum of 50 characters), this will show up on statement of the counterparty.
amount string The amount (cents) of the payment.
tags object See Tags.

Relationships

Name Type Description
account JSON:API Relationship The Deposit Account creating the payment.
customer JSON:API Relationship The Customer the deposit account belongs to. The customer is either a business or a individual.
counterpartyAccount JSON:API Relationship The Counterparty account the payment to be made to.
counterpartyCustomer JSON:API Relationship The Customer the counterparty account belongs to. The customer is either a business or a individual.
transaction JSON:API Relationship The Book Transaction generated by this payment.

Originated ACH Transaction

Example OriginatedAchTransaction resource:

{
  "type": "originatedAchTransaction",
  "id": "1",
  "attributes": {
    "createdAt": "2020-09-06T07:51:02.570Z",
    "direction": "Credit",
    "amount": 10000,
    "balance": 10000,
    "summary": "Counterparty: Unit Inc | Description: Funding",
    "description": "Funding",
    "counterparty": {
      "name": "Unit Inc",
      "routingNumber": "812345678",
      "accountNumber": "1",
      "accountType": "Checking"
    }
  },
  "relationships": {
    "account": {
      "data": {
        "type": "account",
        "id": "10001"
      }
    },
    "customer": {
      "data": {
        "type": "customer",
        "id": "3"
      }
    },
    "payment": {
      "data": {
        "type": "payment",
        "id": "5"
      }
    }
  }
}

OriginatedAchTransaction is a JSON:API resource, top-level fields:

Field type Description
id string Identifier of the transaction resource.
type string Type of the transaction resource. The value is always originatedAchTransaction.
attributes JSON Object JSON object representing the transaction data.
relationships JSON:API Relationships Describes relationships between the transaction resource and other resources (account and customer).

Attributes

Field type Description
createdAt RFC3339 Date string The date the transaction was created. Common to all transaction types.
direction string The direction in which the funds flow. Common to all transaction types.
amount integer The amount (cents) of the transaction. Common to all transaction types.
balance integer The account balance (cents) after the transaction. Common to all transaction types.
summary string Summary of the transaction. Common to all transaction types.
description string Transaction description.
counterparty Counterparty The party on the other end of the transaction.
tags object See Tags. Inherited from the payment tags (see Tag Inheritance).

Relationships

Field type Description
account JSON:API Relationship The Deposit Account of the customer.
customer JSON:API Relationship The customer the deposit account belongs to. The customer is either a business or a individual.
payment JSON:API Relationship The payment belonging to this transaction.

Received ACH Transaction

Example ReceivedAchTransaction resource:

{
  "type": "receivedAchTransaction",
  "id": "4",
  "attributes": {
    "createdAt": "2020-09-08T12:41:43.360Z",
    "direction": "Debit",
    "amount": 80000,
    "balance": 90000,
    "summary": "Company: Unit Inc | Description: Payment from Unit Inc.",
    "description": "Payment from Unit Inc.",
    "companyName": "Unit Inc",
    "counterpartyRoutingNumber": "812345678",
    "traceNumber": "021214860002342",
    "secCode": "WEB"
  },
  "relationships": {
    "account": {
      "data": {
        "type": "account",
        "id": "1"
      }
    },
    "customer": {
      "data": {
        "type": "customer",
        "id": "3"
      }
    }
  }
}

ReceivedAchTransaction is a JSON:API resource, top-level fields:

Field type Description
id string Identifier of the transaction resource.
type string Type of the transaction resource. The value is always receivedAchTransaction.
attributes JSON Object JSON object representing the transaction data.
relationships JSON:API Relationships Describes relationships between the transaction resource and other resources (account and customer).

Attributes

Field type Description
createdAt RFC3339 Date string The date the transaction was created. Common to all transaction types.
direction string The direction in which the funds flow. Common to all transaction types.
amount integer The amount (cents) of the transaction. Common to all transaction types.
balance integer The account balance (cents) after the transaction. Common to all transaction types.
summary string Summary of the transaction. Common to all transaction types.
description string Transaction description.
addenda string Optional. Additional transaction description (maximum of 50 characters).
companyName string The name by which the originator is known to the receiver.
counterpartyRoutingNumber string The routing number of the party that originated the ACH payment.
traceNumber string The ACH Trace Number.
secCode string Optional. The 3-letter ACH Standard Entry Class (SEC) Code (e.g. WEB, CCD, PPD, etc.).
tags object See Tags.

Relationships

Field type Description
account JSON:API Relationship The Deposit Account of the customer.
customer JSON:API Relationship The customer the deposit account belongs to. The customer is either a business or a individual.

Returned ACH Transaction

Example ReturnedAchTransaction resource:

{
  "type": "returnedAchTransaction",
  "id": "4",
  "attributes": {
    "createdAt": "2020-09-08T12:41:43.360Z",
    "direction": "Debit",
    "amount": 1000,
    "balance": 9000,
    "summary": "Return due to: NoAccount | Counterparty: Unit Inc",
    "companyName": "Unit Inc",
    "counterpartyName": "Unit Inc",
    "counterpartyRoutingNumber": "812345678",
    "reason": "NoAccount"
  },
  "relationships": {
    "account": {
      "data": {
        "type": "account",
        "id": "1"
      }
    },
    "customer": {
      "data": {
        "type": "customer",
        "id": "3"
      }
    },
    "payment": {
      "data": {
        "type": "payment",
        "id": "1"
      }
    }
  }
}

ReturnedAchTransaction is a JSON:API resource, top-level fields:

Field type Description
id string Identifier of the transaction resource.
type string Type of the transaction resource. The value is always returnedAchTransaction.
attributes JSON Object JSON object representing the transaction data.
relationships JSON:API Relationships Describes relationships between the transaction resource and other resources (account and customer).

Attributes

Field type Description
createdAt RFC3339 Date string The date the transaction was created. Common to all transaction types.
direction string The direction in which the funds flow. Common to all transaction types.
amount integer The amount (cents) of the transaction. Common to all transaction types.
balance integer The account balance (cents) after the transaction. Common to all transaction types.
summary string Summary of the transaction. Common to all transaction types.
companyName string The name by which the originator is known to the receiver.
counterpartyName string The name of the party that originated the ACH payment.
counterpartyRoutingNumber string The routing number of the party that originated the ACH payment.
reason string The reason for the transaction return.
tags object See Tags.

Relationships

Field type Description
account JSON:API Relationship The Deposit Account of the customer.
customer JSON:API Relationship The customer the deposit account belongs to. The customer is either a business or a individual.
payment JSON:API Relationship The returned payment.

Returned Received ACH Transaction

Example ReturnedReceivedAchTransaction resource:

{
  "type": "returnedReceivedAchTransaction",
  "id": "4",
  "attributes": {
    "createdAt": "2020-09-08T12:41:43.360Z",
    "direction": "Debit",
    "amount": 1000,
    "balance": 500,
    "summary": "Returned received ACH transaction #55 due to: InsufficientFunds",
    "companyName": "John Doe",    
    "reason": "InsufficientFunds"
  },
  "relationships": {
    "account": {
      "data": {
        "type": "account",
        "id": "1"
      }
    },
    "customer": {
      "data": {
        "type": "customer",
        "id": "3"
      }
    },
    "returned": {
      "data": {
        "type": "transaction",
        "id": "55"
      }
    }
  }
}

The transaction is used to return a received ACH, automatically by Unit (e.g insufficient funds) or by a dispute.

ReturnedReceivedAchTransaction is a JSON:API resource, top-level fields:

Field type Description
id string Identifier of the transaction resource.
type string Type of the transaction resource. The value is always returnedAchTransaction.
attributes JSON Object JSON object representing the transaction data.
relationships JSON:API Relationships Describes relationships between the transaction resource and other resources (account and customer).

Attributes

Field type Description
createdAt RFC3339 Date string The date the transaction was created. Common to all transaction types.
direction string The direction in which the funds flow. Common to all transaction types.
amount integer The amount (cents) of the transaction. Common to all transaction types.
balance integer The account balance (cents) after the transaction. Common to all transaction types.
summary string Summary of the transaction. Common to all transaction types.
companyName string The name by which the originator is known to the receiver.
reason string The reason for the transaction return.
tags object See Tags.

Relationships

Field type Description
account JSON:API Relationship The Deposit Account of the customer.
customer JSON:API Relationship The customer the deposit account belongs to. The customer is either a business or a individual.
returned JSON:API Relationship The returned transaction.

Book Transaction

Example BookTransaction resource:

{
  "type": "bookTransaction",
  "id": "9547",
  "attributes": {
    "createdAt": "2020-07-05T15:49:36.864Z",
    "direction": "Credit",
    "amount": 1000,
    "balance": 12000,
    "summary": "Counterparty: Jane Smith | Description: Gift",
    "counterparty": {
      "name": "Jane Smith",
      "routingNumber": "812345678",
      "accountNumber": "10039",
      "accountType": "Checking"
    }
  },
  "relationships": {
    "account": {
      "data": {
        "type": "depositAccount",
        "id": "10035"
      }
    },
    "customer": {
      "data": {
        "type": "customer",
        "id": "5"
      }
    },
    "counterpartyAccount": {
      "data": {
        "type": "account",
        "id": "10036"
      }
    },
    "counterpartyCustomer": {
      "data": {
        "type": "customer",
        "id": "7"
      }
    }
  }
}

BookTransaction is a JSON:API resource, top-level fields:

Field type Description
id string Identifier of the transaction resource.
type string Type of the transaction resource. The value is always bookTransaction.
attributes JSON Object JSON object representing the transaction data.
relationships JSON:API Relationships Describes relationships between the transaction resource and other resources (account and customer).
tags object See Tags. Inherited from the payment tags (see Tag Inheritance).

Attributes

Field type Description
createdAt RFC3339 Date string The date the transaction was created. Common to all transaction types.
direction string The direction in which the funds flow. Common to all transaction types.
amount integer The amount (cents) of the transaction. Common to all transaction types.
balance integer The account balance (cents) after the transaction. Common to all transaction types.
summary string Summary of the transaction. Common to all transaction types.
counterparty Counterparty The party on the other end of the transaction.

Relationships

Field type Description
account JSON:API Relationship The Deposit Account of the customer.
customer JSON:API Relationship The customer the deposit account belongs to. The customer is either a business or a individual.
counterpartyAccount JSON:API Relationship The account of the counterparty.
counterpartyCustomer JSON:API Relationship The counterparty customer.

Purchase Transaction

Example PurchaseTransaction resource:

{
  "type": "purchaseTransaction",
  "id": "51",
  "attributes": {
    "createdAt": "2020-09-08T12:41:43.360Z",
    "direction": "Debit",
    "amount": 2500,
    "balance": 10523,
    "summary": "Car rental",
    "cardLast4Digits": "2282",
    "merchant": {
      "name": "Europcar Mobility Group",
      "type": 3381,
      "category": "EUROP CAR",
      "location": "Cupertino, CA"
    },
    "coordinates": {
      "longitude": -77.0364,
      "latitude": 38.8951
    },
    "recurring": false
  },
  "relationships": {
    "account": {
      "data": {
        "type": "account",
        "id": "10001"
      }
    },
    "customer": {
      "data": {
        "type": "customer",
        "id": "3"
      }
    },
    "card": {
      "data": {
        "type": "card",
        "id": "11"
      }
    },
    "authorization": {
      "data": {
        "type": "authorization",
        "id": "40"
      }
    }
  }
}

PurchaseTransaction is a JSON:API resource, top-level fields:

Field type Description
id string Identifier of the transaction resource.
type string Type of the transaction resource. The value is always purchaseTransaction.
attributes JSON Object JSON object representing the transaction data.
relationships JSON:API Relationships Describes relationships between the transaction resource and other resources (account and customer).

Attributes

Field type Description
createdAt RFC3339 Date string The date the transaction was created. Common to all transaction types.
direction string The direction in which the funds flow. Common to all transaction types.
amount integer The amount (cents) of the transaction. Common to all transaction types.
balance integer The account balance (cents) after the transaction. Common to all transaction types.
summary string Summary of the transaction. Common to all transaction types.
cardLast4Digits string The last 4 digits of the debit card involved in the transaction.
merchant.name string The name of the merchant.
merchant.type integer The 4-digit ISO 18245 merchant category code (MCC).
merchant.category string The merchant category, described by the MCC code (see this reference for the list of category descriptions).
merchant.location string Optional. The location (city, state, etc.) of the merchant.
coordinates Coordinates Optional. Coordinates (latitude, longitude) of where the purchase took place.
recurring boolean Indicates whether the transaction is recurring
tags object See Tags.

Relationships

Field type Description
account JSON:API Relationship The Deposit Account of the customer.
customer JSON:API Relationship The customer the deposit account belongs to. The customer is either a business or a individual.
card JSON:API Relationship The debit card involved in the transaction.
authorization JSON:API Relationship Optional. The Authorization request made by the merchant, if present (see Authorizations).

ATM Transaction

Example AtmTransaction resource:

{
  "type": "atmTransaction",
  "id": "1432",
  "attributes": {
    "createdAt": "2020-07-05T15:49:36.864Z",
    "direction": "Credit",
    "amount": 10000,
    "balance": 12000,
    "summary": "ATM deposit",
    "cardLast4Digits": "2282",
    "atmName": "First National Bank",
    "atmLocation": "Masontown, PA 15461",
    "surcharge": 10
  },
  "relationships": {
    "account": {
      "data": {
        "type": "depositAccount",
        "id": "1000"
      }
    },
    "customer": {
      "data": {
        "type": "customer",
        "id": "3"
      }
    },
    "card": {
      "data": {
        "type": "card",
        "id": "11"
      }
    }
  }
}

AtmTransaction is a JSON:API resource, top-level fields:

Field type Description
id string Identifier of the transaction resource.
type string Type of the transaction resource. The value is always atmTransaction.
attributes JSON Object JSON object representing the transaction data.
relationships JSON:API Relationships Describes relationships between the transaction resource and other resources (account and customer).

Attributes

Field type Description
createdAt RFC3339 Date string The date the transaction was created. Common to all transaction types.
direction string The direction in which the funds flow. Common to all transaction types.
amount integer The amount (cents) of the transaction, including the surcharge fee. Common to all transaction types.
balance integer The account balance (cents) after the transaction. Common to all transaction types.
summary string Summary of the transaction. Common to all transaction types.
cardLast4Digits string The last 4 digits of the debit card involved in the transaction.
atmName string The name of the ATM.
atmLocation string Optional. The location (city, state, etc.) of the ATM.
surcharge number The surcharge fee (cents) for the transaction.
tags object See Tags.

Relationships

Field type Description
account JSON:API Relationship The Deposit Account of the customer.
customer JSON:API Relationship The customer the deposit account belongs to. The customer is either a business or a individual.
card JSON:API Relationship The debit card involved in the transaction.

Fee Transaction

Example FeeTransaction resource:

{
  "type": "feeTransaction",
  "id": "388",
  "attributes": {
    "createdAt": "2020-09-08T12:41:43.360Z",
    "direction": "Debit",
    "amount": 10,
    "balance": 89980,
    "summary": "Payment fee for transaction #4"
  },
  "relationships": {
    "account": {
      "data": {
        "type": "account",
        "id": "10001"
      }
    },
    "customer": {
      "data": {
        "type": "customer",
        "id": "3"
      }
    },
    "relatedTransaction": {
      "data": {
        "type": "transaction",
        "id": "4"
      }
    }
  }
}

FeeTransaction is a JSON:API resource, top-level fields:

Field type Description
id string Identifier of the transaction resource.
type string Type of the transaction resource. The value is always feeTransaction.
attributes JSON Object JSON object representing the transaction data.
relationships JSON:API Relationships Describes relationships between the transaction resource and other resources (account, customer and relatedTransaction).

Attributes

Field type Description
createdAt RFC3339 Date string The date the transaction was created. Common to all transaction types.
direction string The direction in which the funds flow. Common to all transaction types.
amount integer The amount (cents) of the transaction. Common to all transaction types.
balance integer The account balance (cents) after the transaction. Common to all transaction types.
summary string Summary of the transaction. Common to all transaction types.
tags object See Tags.

Relationships

Field type Description
account JSON:API Relationship The Deposit Account of the customer.
customer JSON:API Relationship The customer the deposit account belongs to. The customer is either a business or a individual.
relatedTransaction JSON:API Relationship Optional. The transaction which the fee is subject to.

Card Reversal Transaction

Example CardReversalTransaction resource:

{
  "type": "cardReversalTransaction",
  "id": "401",
  "attributes": {
    "createdAt": "2020-09-14T12:41:43.360Z",
    "direction": "Debit",
    "amount": 10,
    "balance": 89980,
    "summary": "Reversal for transaction #400",
    "cardLast4Digits": "2282"
  },
  "relationships": {
    "account": {
      "data": {
        "type": "account",
        "id": "10001"
      }
    },
    "customer": {
      "data": {
        "type": "customer",
        "id": "1001"
      }
    },
    "relatedTransaction": {
      "data": {
        "type": "transaction",
        "id": "400"
      }
    }
  }
}

CardReversalTransaction is a JSON:API resource, top-level fields:

Field type Description
id string Identifier of the transaction resource.
type string Type of the transaction resource. The value is always cardReversalTransaction.
attributes JSON Object JSON object representing the transaction data.
relationships JSON:API Relationships Describes relationships between the transaction resource and other resources (account, customer and relatedTransaction).

Attributes

Field type Description
createdAt RFC3339 Date string The date the transaction was created. Common to all transaction types.
direction string The direction in which the funds flow. Common to all transaction types.
amount integer The amount (cents) of the transaction. Common to all transaction types.
balance integer The account balance (cents) after the transaction. Common to all transaction types.
summary string Summary of the transaction. Common to all transaction types.
cardLast4Digits string The last 4 digits of the debit card involved in the transaction.
tags object See Tags.

Relationships

Field type Description
account JSON:API Relationship The Deposit Account of the customer.
customer JSON:API Relationship The customer the deposit account belongs to. The customer is either a business or a individual.
relatedTransaction JSON:API Relationship Optional. The transaction which the reversal is related to.

Card Transaction

Example CardTransaction resource:

{
  "type": "cardTransaction",
  "id": "410",
  "attributes": {
    "createdAt": "2020-09-20T12:41:43.360Z",
    "direction": "Debit",
    "amount": 10,
    "balance": 89480,
    "summary": "Card transaction details",
    "cardLast4Digits": "2282"
  },
  "relationships": {
    "account": {
      "data": {
        "type": "account",
        "id": "10001"
      }
    },
    "customer": {
      "data": {
        "type": "customer",
        "id": "1001"
      }
    }
  }
}

CardTransaction is a JSON:API resource, top-level fields:

Field type Description
id string Identifier of the transaction resource.
type string Type of the transaction resource. The value is always cardTransaction.
attributes JSON Object JSON object representing the transaction data.
relationships JSON:API Relationships Describes relationships between the transaction resource and other resources (account and customer).

Attributes

Field type Description
createdAt RFC3339 Date string The date the transaction was created. Common to all transaction types.
direction string The direction in which the funds flow. Common to all transaction types.
amount integer The amount (cents) of the transaction. Common to all transaction types.
balance integer The account balance (cents) after the transaction. Common to all transaction types.
summary string Summary of the transaction. Common to all transaction types.
cardLast4Digits string The last 4 digits of the debit card involved in the transaction.
tags object See Tags.

Relationships

Field type Description
account JSON:API Relationship The Deposit Account of the customer.
customer JSON:API Relationship The customer the deposit account belongs to. The customer is either a business or a individual.

Wire Transaction

Example WireTransaction resource:

{
  "type": "wireTransaction",
  "id": "9547",
  "attributes": {
    "createdAt": "2020-07-05T15:49:36.864Z",
    "direction": "Credit",
    "amount": 1000,
    "balance": 12000,
    "summary": "Wire from Jane Smith",
    "counterparty": {
      "name": "Jane Smith",
      "routingNumber": "812345678",
      "accountNumber": "10039",
      "accountType": "Checking"
    }
  },
  "relationships": {
    "account": {
      "data": {
        "type": "depositAccount",
        "id": "10035"
      }
    },
    "customer": {
      "data": {
        "type": "customer",
        "id": "5"
      }
    }
  }
}

WireTransaction is a JSON:API resource, top-level fields:

Field type Description
id string Identifier of the transaction resource.
type string Type of the transaction resource. The value is always wireTransaction.
attributes JSON Object JSON object representing the transaction data.
relationships JSON:API Relationships Describes relationships between the transaction resource and other resources (account and customer).

Attributes

Field type Description
createdAt RFC3339 Date string The date the transaction was created. Common to all transaction types.
direction string The direction in which the funds flow. Common to all transaction types.
amount integer The amount (cents) of the transaction. Common to all transaction types.
balance integer The account balance (cents) after the transaction. Common to all transaction types.
summary string Summary of the transaction. Common to all transaction types.
counterparty Counterparty The party on the other end of the transaction, either the beneficiary or the originator.
description string Description of the transaction as entered by the originator. Also known as OBI or “Originator to Beneficiary Information”.
senderReference string Sender reference.
referenceForBeneficiary string Reference for the Beneficiary.
tags object See Tags.

Relationships

Field type Description
account JSON:API Relationship The Deposit Account of the customer.
customer JSON:API Relationship The customer the deposit account belongs to. The customer is either a business or a individual.

Release Transaction

Example ReleaseTransaction resource:

{
  "type": "releaseTransaction",
  "id": "258",
  "attributes": {
    "createdAt": "2020-12-08T15:38:07.394Z",
    "senderName": "Richard Hendricks",
    "senderAddress": {
      "street": "5230 Newell Rd",
      "city": "Palo Alto",
      "state": "CA",
      "postalCode": "94303",
      "country": "US"
    },
    "senderAccountNumber": "123456798",
    "counterparty": {
      "name": "BatchAccount15",
      "routingNumber": "812345678",
      "accountNumber": "1000000096",
      "accountType": "Checking"
    },
    "amount": 1000,
    "direction": "Credit",
    "description": "First Payment",
    "balance": 1000,
    "summary": "First Payment  |  Richard Hendricks"
  },
  "relationships": {
    "account": {
      "data": {
        "type": "account",
        "id": "10097"
      }
    }
  }
}

ReleaseTransaction is a JSON:API resource, top-level fields:

Field type Description
id string Identifier of the transaction resource.
type string Type of the transaction resource. The value is always releaseTransaction.
attributes JSON Object JSON object representing the transaction data.
relationships JSON:API Relationships Describes relationships between the transaction resource and other resources (account).

Attributes

Field type Description
createdAt RFC3339 Date string The date the transaction was created. Common to all transaction types.
senderName string Name of the sender.
senderAddress Address Address of the sender.
senderAccountNumber string Unique identifier to monitor for similar sending accounts, could be the BIN + last four digits of the card number OR a unique identifier generated by you for the sender.
counterparty Counterparty The party who is releasing the funds
amount integer The amount (cents) of the transaction. Common to all transaction types.
direction string The direction in which the funds flow. Common to all transaction types. The value is always Credit.
description string Description of the payment.
balance integer The account balance (cents) after the transaction. Common to all transaction types.
summary string Summary of the transaction. Common to all transaction types.
tags object See Tags.

Relationships

Field type Description
account JSON:API Relationship The Deposit Account receiving the funds.

Adjustment Transaction

Example AdjustmentTransaction resource:

{
  "type": "adjustmentTransaction",
  "id": "215",
  "attributes": {
    "createdAt": "2021-04-12T16:08:39.040Z",
    "amount": 5000,
    "direction": "Debit",
    "balance": 3124000,
    "summary": "correction of transaction #200",
    "description": "correction of transaction #200"
  },
  "relationships": {
    "account": {
      "data": {
        "type": "account",
        "id": "10001"
      }
    },
    "customer": {
      "data": {
        "type": "customer",
        "id": "10000"
      }
    }
  }
}

AdjustmentTransaction is a JSON:API resource, top-level fields:

Field type Description
id string Identifier of the transaction resource.
type string Type of the transaction resource. The value is always adjustmentTransaction.
attributes JSON Object JSON object representing the transaction data.
relationships JSON:API Relationships Describes relationships between the transaction resource and other resources (account).

Attributes

Field type Description
createdAt RFC3339 Date string The date the transaction was created. Common to all transaction types.
direction string The direction in which the funds flow. Common to all transaction types.
amount integer The amount (cents) of the transaction. Common to all transaction types.
balance integer The account balance (cents) after the transaction. Common to all transaction types.
summary string Summary of the transaction. Common to all transaction types.
description string Description of the transaction.
tags object See Tags.

Relationships

Field type Description
account JSON:API Relationship The Deposit Account participating in the transaction.

Interest Transaction

Example InterestTransaction resource:

{
  "type": "interestTransaction",
  "id": "9547",
  "attributes": {
    "createdAt": "2020-07-05T15:49:36.864Z",
    "direction": "Credit",
    "amount": 1000,
    "balance": 12000,
    "summary": "Interest March 2020"
  },
  "relationships": {
    "account": {
      "data": {
        "type": "depositAccount",
        "id": "10035"
      }
    },
    "customer": {
      "data": {
        "type": "customer",
        "id": "5"
      }
    }
  }
}

InterestTransaction is a JSON:API resource, top-level fields:

Field type Description
id string Identifier of the transaction resource.
type string Type of the transaction resource. The value is always interestTransaction.
attributes JSON Object JSON object representing the transaction data.
relationships JSON:API Relationships Describes relationships between the transaction resource and other resources (account and customer).

Attributes

Field type Description
createdAt RFC3339 Date string The date the transaction was created. Common to all transaction types.
direction string The direction in which the funds flow. Common to all transaction types.
amount integer The amount (cents) of the transaction. Common to all transaction types.
balance integer The account balance (cents) after the transaction. Common to all transaction types.
summary string Summary of the transaction. Common to all transaction types.
tags object See Tags.

Relationships

Field type Description
account JSON:API Relationship The Deposit Account of the customer.
customer JSON:API Relationship The customer the deposit account belongs to. The customer is either a business or a individual.

Dispute Transaction

Example DisputeTransaction resource:

{
  "type": "disputeTransaction",
  "id": "226",
  "attributes": {
    "createdAt": "2021-04-19T12:44:08.055Z",
    "amount": 2500,
    "direction": "Credit",
    "balance": 550000,
    "summary": "Dispute 119 | Provisional Credit",
    "reason": "ProvisionalCredit"
  },
  "relationships": {
    "account": {
      "data": {
        "type": "account",
        "id": "10001"
      }
    },
    "customer": {
      "data": {
        "type": "customer",
        "id": "10000"
      }
    }
  }
}

DisputeTransaction is a JSON:API resource, top-level fields:

Field type Description
id string Identifier of the transaction resource.
type string Type of the transaction resource. The value is always disputeTransaction.
attributes JSON Object JSON object representing the transaction data.
relationships JSON:API Relationships Describes relationships between the transaction resource and other resources (account, customer).

Attributes

Field type Description
createdAt RFC3339 Date string The date the transaction was created. Common to all transaction types.
direction string The direction in which the funds flow. Common to all transaction types.
amount integer The amount (cents) of the transaction. Common to all transaction types.
balance integer The account balance (cents) after the transaction. Common to all transaction types.
summary string Summary of the transaction. Common to all transaction types.
reason string The reason for the dispute transaction, one of: ProvisionalCredit, ProvisionalCreditReversalDenied, ProvisionalCreditReversalResolved, FinalCredit.
tags object See Tags.

Relationships

Field type Description
account JSON:API Relationship The Deposit Account participating in the transaction.
customer JSON:API Relationship The customer the deposit account belongs to. The customer is either a business or a individual.

Authorization

Example Authorization resource:

{
  "type": "authorization",
  "id": "97",
  "attributes": {
    "createdAt": "2021-02-21T07:29:42.447Z",
    "amount": 2000,
    "cardLast4Digits": "0019",
    "merchant": {
      "name": "Europcar Mobility Group",
      "type": 3381,
      "category": "EUROP CAR",
      "location": "Cupertino, CA"
    },
    "recurring": false
  },
  "relationships": {
    "customer": {
      "data": {
        "type": "customer",
        "id": "10000"
      }
    },
    "account": {
      "data": {
        "type": "account",
        "id": "10001"
      }
    }
  }
}

Authorization is a JSON:API resource, top-level fields:

Field type Description
id string Identifier of the authorization resource.
type string Type of the authorization resource. The value is always authorization.
attributes JSON Object JSON object representing the authorization data.
relationships JSON:API Relationships Describes relationships between the authorization resource and other resources (account and customer).

Attributes

Field type Description
createdAt RFC3339 Date string The date the authorization was created.
amount integer The amount (cents) of the authorization.
cardLast4Digits string The last 4 digits of the debit card involved in the authorization.
merchant.name string The name of the merchant.
merchant.type integer The 4-digit ISO 18245 merchant category code (MCC).
merchant.category string The merchant category, described by the MCC code (see this reference for the list of category descriptions).
merchant.location string Optional. The location (city, state, etc.) of the merchant.
recurring boolean Indicates whether the authorization is recurring

Relationships

Field type Description
account JSON:API Relationship The Deposit Account of the customer.
customer JSON:API Relationship The customer the deposit account belongs to. The customer is either a business or a individual.

Statement

Example Statement resource:

  {
    "type": "statement",
    "id": "1",
    "attributes": {
      "period": "2020-07"
    },
    "relationships": {
      "account": {
        "data": {
          "type": "account",
          "id": "1000"
        }
      },
      "customer": {
        "data": {
          "type": "customer",
          "id": "1"
        }
      }
    }
  }

Statement is a JSON:API resource, top-level fields:

Field type Description
id string Identifier of the statement resource.
type string Type of the statement resource. The value is always statement.
attributes JSON Object JSON object representing the statement data.
relationships JSON:API Relationships Describes relationships between the statement resource and other resources (account and customer).

Attributes

Field type Description
period string Period of the statement, formatted YYYY-MM, e.g "2020-05".

Relationships

Field type Description
account JSON:API Relationship The account for which the statement was produced.
customer JSON:API Relationship The individual or business customer the account belongs to.

BatchRelease

Example BatchRelease resource:

{
  "type": "batchRelease",
  "id": "100123",
  "attributes": {
    "amount": 3000,
    "description": "Gift",
    "senderName": "Sherlock Holmes",
    "senderAccountNumber": "4581133972",
    "senderAddress": {
      "street": "221B Baker Street",
      "city": "London",
      "postalCode": "NW1 6XE",
      "country": "UK"
    }
  },
  "relationships": {
    "batchAccount": {
      "data": {
        "type": "batchAccount",
        "id": "10104"
      }
    },
    "receiver": {
      "data": {
        "type": "depositAccount",
        "id": "10097"
      }
    }
  }
}

BatchRelease is a JSON:API resource, top-level fields:

Field type Description
id string Identifier of the batch-release resource.
type string Type of the batch-release resource. The value is always batchRelease.
attributes JSON Object JSON object representing the batch-release data.
relationships JSON:API Relationships Describes relationships between the batch-release resource and other resources (accounts).

Attributes

Name Type Description
amount integer The amount (in cents) to move from the batch account to the receiver account.
description string Description of the payment.
senderName string Name of the sender, before combining the payments.
senderAddress Address Address of the sender.
senderAccountNumber string Unique identifier to monitor for similar sending accounts, could be the BIN + last four digits of the card number OR a unique identifier generated by you for the sender.

Relationships

Name Type Description
batchAccount JSON:API Relationship The batch account to release the funds from.
receiver JSON:API Relationship The account to release the funds to.

Fee

Example Fee resource:

{
  "data": {
    "type": "fee",
    "id": "1234",
    "attributes": {
      "amount": 1000,
      "description": "Monthly Subscription"
    },
    "relationships": {
      "account": {
        "data": {
          "type": "depositAccount",
          "id": "10097"
        }
      }
    }
  }
}

Fee is a JSON:API resource, top-level fields:

Field type Description
id string Identifier of the fee resource.
type string Type of the fee resource. The value is always fee.
attributes JSON Object JSON object representing the fee data.
relationships JSON:API Relationships Describes relationships between the fee resource and other resources (accounts).

Attributes

Name Type Description
amount integer The amount (in cents) of the fee.
description string Description of the fee.
tags object See Tags.
idempotencyKey string See Idempotency.

Relationships

Name Type Description
account JSON:API Relationship The account the fee belongs to.

Event

Example Event resource:

{
  "data": [
    {
      "id": "230",
      "type": "transaction.created",
      "attributes": {
        "createdAt": "2021-03-15T07:49:09.089Z",
        "amount": 10000,
        "direction": "Credit",
        "summary": "Wire from Sender"
      },
      "relationships": {
        "account": {
          "data": {
            "id": "10005",
            "type": "account"
          }
        },
        "transaction": {
          "data": {
            "id": "189",
            "type": "wireTransaction"
          }
        },
        "customer": {
          "data": {
            "id": "10000",
            "type": "individualCustomer"
          }
        }
      }
    }
  ]
}

Event is a JSON:API resource, top-level fields:

Field type Description
id string Identifier of the event resource.
type string Type of the event resource.
attributes JSON Object JSON object representing the event data, based on the event type. See Events.
relationships JSON:API Relationships Describes relationships between the event resource and other resources, based on the event type. See Events.

Types

FullName

Example FullName type:

{
    "first": "Peter",
    "last": "Parker"
}
Field Type Description
first string Individual first name.
last string Individual last name.

Address

Example Address type:

{
    "street": "20 Ingram St",
    "street2": "Apt #10",
    "city": "Forest Hills",
    "state": "NY",
    "postalCode": "11375",
    "country": "US"
}
Field Type Description
street string First line of an address.
street2 string Optional. Second line of an address.
city string City.
state string Two letters representing the state. Only required for US addresses.
postalCode string Postal code.
country ISO31661-Alpha2 string Two letters representing the country.

Phone

Example Phone type:

{
    "countryCode": "1",
    "number": "15555555"
}
Field Type Description
countryCode string Country code of the phone number, e.g. "1" for US.
number string The phone number without the country code, e.g. "4151193497".

Officer

Example Officer type:

{
    "fullName": {
        "first": "Richard",
        "last": "Hendricks"
    },	
    "dateOfBirth": "2001-08-15",
    "ssn": "721074426",
    "email": "richard@piedpiper.com",
    "phone": {
        "countryCode": "1",
        "number": "5555555"
    },
    "address": {
        "street": "5230 Newell Rd",
        "city": "Palo Alto",
        "state": "CA",
        "postalCode": "94303",
        "country": "US"
    }
}
Field Type Description
status string One of Approved, Denied or PendingReview.
fullName FullName Full name of the officer.
title string One of CEO, COO, CFO or President.
ssn string SSN of the officer (numbers only). One of ssn or passport is required.
passport string Passport of the officer. One of ssn or passport is required.
nationality ISO31661-Alpha2 string Only when Passport is populated. Two letters representing the officer's nationality.
dateOfBirth RFC3339 Date string Date only (e.g. "2001-08-15").
address Address The officer's address.
phone Phone The officer's phone number.
email string The officer's email address.

BeneficialOwner

Example BeneficialOwner type:

{
    "fullName": {
        "first": "Richard",
        "last": "Hendricks"
    },	
    "dateOfBirth": "2001-08-15",
    "ssn": "721074426",
    "email": "richard@piedpiper.com",
    "phone": {
        "countryCode": "1",
        "number": "5555555"
    },
    "address": {
        "street": "5230 Newell Rd",
        "city": "Palo Alto",
        "state": "CA",
        "postalCode": "94303",
        "country": "US"
    }
}
Field Type Description
status string One of Approved, Denied or PendingReview.
fullName FullName Full name of the beneficial owner.
ssn string SSN of the officer (numbers only). One of ssn or passport is required.
passport string Passport of the beneficial owner. One of ssn or passport is required.
nationality ISO31661-Alpha2 string Only when Passport is populated. Two letters representing the beneficial owner's nationality.
dateOfBirth RFC3339 Date string Date only (e.g. "2001-08-15").
address Address The beneficial owner's address.
phone Phone The beneficial owner's phone number.
email string The beneficial owner's email address.
percentage string The beneficial owner percentage of ownership at the business.

BusinessContact

Example BusinessContact type:

{
    "fullName": {
        "first": "Richard",
        "last": "Hendricks"
    },
    "email": "richard@piedpiper.com",
    "phone": {
        "countryCode": "1",
        "number": "5555555"
    }
}
Field Type Description
fullName FullName Full name of the contact.
email string The contact's email address.
phone Phone The contact's phone number.

AuthorizedUser

Example AuthorizedUser type:

{
    "fullName": {
        "first": "Richard",
        "last": "Hendricks"
    },
    "username":"richard",
    "email": "richard@piedpiper.com",
    "phone": {
        "countryCode": "1",
        "number": "5555555"
    }
}
Field Type Description
fullName FullName Full name of the authorized user.
username string The authorized user's username.
email string The authorized user's email address.
phone Phone The authorized user's phone number. This number will be used for One Time Password (OTP) authentication.

Counterparty

Example Counterparty type:

{
    "counterparty": {
        "routingNumber": "812345678",
        "accountNumber": "12345569",
        "accountType": "Checking",
        "name": "Jane Doe"
    }
}
Field Type Description
routingNumber string Valid 9-digit ABA routing transit number.
accountNumber string Bank account number.
accountType string Either Checking or Savings.
name string Name of the person or company that owns the bank account.

Coordinates

Example Coordinates type:

{
    "longitude": -77.0364,
    "latitude": 38.8951
}
Field Type Description
longitude number The longitude value.
latitude number The latitude value.