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, payments, cards, 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? Please contact us at team@unit.co to 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

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 the bearer token. You can create an API token from the API Tokens page on the Unit Dashboard.

Tags

{
  "data": {
    "type": "depositAccount",
    "attributes": {
      /// ...
      "tags": {
        "purpose": "tax"
      }
    },
    /// ...
}

To help you manage the resources, you can assign your own metadata to the resources in the form of tags. Tags enable you to categorize your resources in different ways. For example, you could define a purpose tag for an account with values: tax, saving or checking.

Tag restrictions

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-10",
    "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:

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:

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 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 an hour 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 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

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",
      "ein": "123456789",
      "dba": "Piedpiper Inc",
      "soleProprietorship": true
    }
  }
}'
Verb POST
Url https://api.s.unit.sh/applications
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 (numbers only). 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 string e.g. "2001-08-10"
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 customer
ein string Optional. The Employer Identification Number of the sole proprietor. Not all sole proprietors have an Employer Identification Number and therefore this is optional also when soleProprietorship is set.
dba String Optional. The sole proprietor “Doing business as” if the sole proprietor has one.
soleProprietorship boolean Default: false. Indicates whether the individual is sole proprietary.

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",
      "ein": "123456789",
      "dba": "Piedpiper Inc",
      "soleProprietorship": true
    },
    "relationships": {
      "org": {
        "data": {
          "type": "org",
          "id": "1"
        }
      },
      "documents": {
        "data": [
          {
            "type": "document",
            "id": "1"
          },
          {
            "type": "document",
            "id": "2"
          }
        ]
      }
    }
  },
  "included": [
    {
      "type": "document",
      "id": "1",
      "attributes": {
        "documentType": "UtilityBill",
        "status": "Required",
        "name": "Peter Parker",
        "address": {
          "street": "20 Ingram St",
          "street2": null,
          "city": "Forest Hills",
          "state": "NY",
          "postalCode": "11375",
          "country": "US"
        }
      }
    },
    {
      "type": "document",
      "id": "2",
      "attributes": {
        "documentType": "DriverLicense",
        "status": "Required",
        "name": "Peter Parker",
        "dateOfBirth": "2001-08-10"
      }
    }
  ]

}

201 Created

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

Create Business Application

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"
          }
        }
      ]
    }
  }
}'
Verb POST
Url https://api.s.unit.sh/applications
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" or "LLC".
ip string IP address of the customer.
website string Business's website.
contact BusinessContact Primary contact of the business
officer Officer Officer representing the business (must be the CEO, COO, CFO or President). 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.

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"
        }
      ],
      "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"
      }
    },
    {
      "type": "document",
      "id": "2",
      "attributes": {
        "documentType": "UtilityBill",
        "status": "Required",
        "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": "DriverLicense",
        "status": "Required",
        "name": "Richard Hendricks"
      }
    }
  ]
}

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

Get an application resource by id.

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

Find

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

Find application resources. Paging can be applied.

Query Parameters

Name Type Default Description
page[limit] number 100 Maximum number of resources that will be returned. Maximum is 1000 resources.
page[offset] number 0 Number of resources to skip.
sort string Optional 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",
        "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",
        "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 DriverLicense document type
ReceivedFront Front-side of the document was received. Back-side is still required. Only relevant for DriverLicense 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
DriverLicense An individual's driver's license. Both front-side and back-side are required
Passport An individual's passport
UtilityBill An individual's utility bill as proof of address
SocialSecurityCard An individual's social security card
CertificateOfIncorporation A business's certificate of incorporation
EINConfirmation A business's EIN confirmation document (either IRS form 147c or IRS form CP-575)

Upload Document

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}

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

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",
            "name": "Richard Hendricks",
            "dateOfBirth": "2001-08-10"
        }
    }
}

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

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

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

Headers

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

Response

Example Response:

{
    "data": {
        "type": "document",
        "id": "3",
        "attributes": {
            "documentType": "DriverLicense",
            "status": "Approved",
            "name": "Richard Hendricks",
            "dateOfBirth": "2001-08-10"
        }
    }
}

Response is a JSON:API document.

200 OK

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

Find

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}

Find application documents.

Response

Example Response:

{
  "data": [
    {
      "type": "document",
      "id": "1",
      "attributes": {
        "documentType": "CertificateOfIncorporation",
        "status": "Required",
        "name": "Pied Piper"
      }
    },
    {
      "type": "document",
      "id": "2",
      "attributes": {
        "documentType": "UtilityBill",
        "status": "Required",
        "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": "DriverLicense",
        "status": "Required",
        "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.

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

Get a customer resource by id.

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

Find

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

Find customer resources. Paging can be applied.

Query Parameters

Name Type Default Description
page[limit] number 100 Maximum number of resources that will be returned. Maximum is 1000 resources
page[offset] number 0 Number of resources to skip
sort string Optional 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"
          }
        }
      },
      "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"
        }
      },
      "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"
      }
    },
    "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).

Verb POST
Url https://api.s.unit.sh/accounts
Data Type depositAccount

Attributes

Name Type Description
depositProduct string The name of the deposit product
tags object Metadata to attach to the account, in the form of key-value pairs

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",
      "depositProduct": "checking",
      "routingNumber": "812345678",
      "accountNumber": "1000000002",
      "currency": "USD",
      "balance": 10000,
      "hold": 0,
      "tags": {
        "purpose": "checking"
      }
    },
    "relationships": {
      "customer": {
        "data": {
          "type": "customer",
          "id": "45555"
        }
      }
    }
  }
}

201 Created

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

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

Get a deposit account resource by id.

Response

Response is a JSON:API document.

200 OK

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

Find

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

Find deposit account resources. Paging can be applied.

Query Parameters

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

Response

Example Response:

{
  "data": [
    {
      "type": "depositAccount",
      "id": "42",
      "attributes": {
        "createdAt": "2000-05-11T10:19:30.409Z",
        "depositProduct": "checking",
        "routingNumber": "812345678",
        "accountNumber": "1000000002",
        "currency": "USD",
        "balance": 10000,
        "hold": 0,
        "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

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 origination, the directions work as follows:

ACH returns are an important concept that must be covered by your code. When you originate an ACH payment (both Debit and Credit), the counterparty's institution may issue a return. Returns are much more common in the case of ACH Debit than ACH Credit, with reasons ranging from unauthorized payment to insufficient funds in the counterparty's account.

The ACH is a batch-based network, processing batches of payments with 3 cutoff times during the day. When you originate an ACH payment, it is created with a Pending status until it is delivered to the ACH network.

Originate an ACH 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": "achPayment",
      "attributes": {
        "amount": 10000,
        "direction": "Credit",
        "counterparty": {
          "routingNumber": "812345678",
          "accountNumber": "12345569",
          "accountType": "Checking",
          "name": "Jane Doe"
        },
        "description": "ACH PMNT"
      },
      "relationships": {
        "account": {
        "data": {
          "type": "depositAccount",
          "id": "555"
        }
      }
    }
  }
}'

To originate an ACH payment, you must create a Payment resource. To create the resource, the id of your deposit account, the counterparty's account number, routing number, name, and account type, as well as the amount (in cents) and direction are required.

Verb POST
Url https://api.s.unit.sh/payments
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 50 characters)

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": "ACH PMNT",
      "direction": "Credit",
      "amount": 10000
    },
    "relationships": {
      "account": {
        "data": {
          "type": "depositAccount",
          "id": "555"
        }
      },
      "customer": {
        "data": {
          "type": "individualCustomer",
          "id": "99823"
        }
      }
    }
  }
}

Response is a JSON:API document.

Receive 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 or returned automatically by Unit. Examples:

To get notified on received ACH payments, you may process the transaction.created webhook and inspect the payload for received ACH transactions.

ACH Status

The ACH network works in batches, and it therefore doesn't provide immediate success responses (only error responses). As payments are being processed, you can track the progress by checking the status attribute on the ACH response object.

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
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 return reason for more details)

Book Transfers

Book transfers are free and instant fund movements between two accounts under the same bank. Common uses for book transfers include:

To initiate a book transfer, originate an ACH Credit payment between two accounts that reside on the same bank. Unit will automatically identify such payments as book transfers and process them instantly and free of charge. The result will be one book transaction in each account.

Cards

The card resource represents a debit card under an account.

Create Individual Debit Card

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"
      }
    },
    "relationships": {
      "account": {
        "data": {
          "type": "depositAccount",
          "id": "2"
        }
      }
    }
  }
}'
Verb POST
Url https://api.s.unit.sh/cards
Data Type individualDebitCard

Creates and ships a 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)

Attributes

Name Type Description
shippingAddress Address Address to ship the card to. Optional, if not specified, the individual address is used

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"
      }
    },
    "relationships": {
      "account": {
        "data": {
          "type": "depositAccount",
          "id": "2"
        }
      },
      "customer": {
        "data": {
          "type": "individualCustomer",
          "id": "2"
        }
      }
    }
  }
}

201 Created

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

Create Business Debit Card

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"
      }
    },
    "relationships": {
      "account": {
        "data": {
          "type": "depositAccount",
          "id": "1"
        }
      }
    }
  }
}'
Verb POST
Url https://api.s.unit.sh/cards
Data Type businessDebitCard

Creates and ships a debit card to 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.

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 (numbers only). 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 string Date of birth of the card holder (e.g. "2001-08-10")
address Address Address of the card holder
phone Phone Phone of the card holder
email string Email address of the card holder

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"
    },
    "relationships": {
      "account": {
        "data": {
          "type": "depositAccount",
          "id": "1"
        }
      },
      "customer": {
        "data": {
          "type": "businessCustomer",
          "id": "1"
        }
      }
    }
  }
}

201 Created

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

Get by Id

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

Get a card resource by id.

Response

Response is a JSON:API document.

200 OK

Field Type Description
data IndividualDebitCard or BusinessDebitCard Card resource, either individual debit card or business debit card, distinguished by the type field

Find

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

Find cards. Filtering and paging can be applied.

Query Parameters

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

Response

Example Response:

{
  "data": [
    {
      "type": "individualDebitCard",
      "id": "1",
      "attributes": {
        "createdAt": "2020-05-10T16:45:02.272Z",
        "last4Digits": "1234",
        "expirationDate": "2022-05"
      },
      "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"
      },
      "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 Array of card resources, each resource can be either business debit card or individual debit card, distinguished by the type field

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 into a deposit account
Returned ACH An ACH payment returned by the bank
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
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

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 number The amount (cents) of the transaction
balance number The account balance (cents) after the transaction
summary string Human-friendly summary of the transaction

Find

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

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

Query Parameters

Name Type Default Description
page[limit] number 100 Maximum number of resources that will be returned. Maximum is 1000 resources
page[offset] number 0 Number of resources to skip
filter[accountId] string Optional Filters the results by the specified account id
filter[customerId] string Optional Filters the results by the specified customer id
sort string Optional Leave empty or provide sort=createdAt for ascending order. Provide sort=-createdAt (leading minus sign) for descending order

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: ACH PYMT",
        "description": "ACH PYMT",
        "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 - ACH PYMT"
      },
      "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

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 Utility Bill, or 000000003 to simulate AwaitingDocuments for Driver License, 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"
    }
  }
}'

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

Received 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 credit your account 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",
          "companyName": "SANDBOX",
          "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.

Card Purchases

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

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

Relationships

Name 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

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
      }
    },
    "relationships": {
      "account": {
        "data": {
          "type": "depositAccount",
          "id": "10001"
        }
      },
      "customer": {
        "data": {
          "type": "customer",
          "id": "2"
        }
      }
    }
  }
}

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.

Find

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

Find statement resources. Filtering and paging can be applied.

Query Parameters

Name Type Default Description
page[limit] number 100 Maximum number of resources that will be returned. Maximum is 1000 resources
page[offset] number 0 Number of resources to skip
filter[accountId] string Optional Filters the results by the specified account id
filter[customerId] string 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

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

Get a statement HTML output by id.

Response

Response is a HTML document.

Webhooks

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

Example events: Application Denied, Customer created, Transaction completed.

When one of those events is triggered, 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.

Types of events

This is a list of all the types of events we currently send, but we are constantly adding more.

Our event types follow a specific structure: resource.event.
Our goal is to design a consistent system that makes things easier to follow and code against.

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

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.

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",
        "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.

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.

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.

transaction.created

Example transaction.created payload:

{
  "data": [
    {
      "id": "34",
      "type": "transaction.created",
      "attributes": {
        "summary": "ACH PYMT",
        "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"
          }
        }
      }
    }
  ]
}

Occurs when a Transaction is created.

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",
    "evaluationOutcome": "Approved"
  },
  "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 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 string e.g. "2001-08-10"

address | Address | Address of the individual phone | Phone | Phone of the individual email | string | Email address of the individual

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

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 Status.
createdAt RFC3339 Date string e.g. "2020-01-13T16:01:19.346Z"
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.
officer Officer Officer representing the business, must be CEO, CFO or President. 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

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": "DriverLicense",
        "status": "Approved",
        "name": "Richard Hendricks",
        "dateOfBirth": "2001-08-10"
    }
}

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 DriverLicense, Passport, UtilityBill, CertificateOfIncorporation or EINConfirmation
name string Name of business or individual
address Address Individual address, present only for the UtilityBill document type
dateOfBirth RFC3339 string 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 EINConfirmation document type
reason string Application Document rejection reason. Might be 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"
    }
  },
  "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 string e.g. "2001-08-10"
address Address Address of the individual
phone Phone Phone of the individual
email string Email address of the individual

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"
      }
    }
  },
  "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 e.g. "2020-01-13T16:01:19.346Z"
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

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",
    "depositProduct": "checking",
    "routingNumber": "812345678",
    "accountNumber": "1000000002",
    "currency": "USD",
    "balance": 10000,
    "hold": 0,
    "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
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)
tags object Metadata attached to the account, in the form of key-value pairs

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

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"
  },
  "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 (numbers only). 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 string Date of birth of the card holder (e.g. "2001-08-10")
address Address Address of the card holder
phone Phone Phone of the card holder
email string Email address of the card holder

Relationships

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

ACH Payment

Example Payment resource:

{
    "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": "ACH PMNT",
        "direction": "Credit",
        "amount": 10000
      },
      "relationships": {
        "account": {
          "data": {
            "type": "depositAccount",
            "id": "555"
          }
        },
        "customer": {
          "data": {
            "type": "individualCustomer",
            "id": "99823"
          }
        }
      }
    }
  }

Payment 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 Transaction description (maximum of 50 characters)
amount string The amount (cents) of the payment

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

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: ACH PYMT",
    "description": "ACH PYMT",
    "counterparty": {
      "name": "Unit Inc",
      "routingNumber": "812345678",
      "accountNumber": "1",
      "accountType": "Checking"
    }
  },
  "relationships": {
    "account": {
      "data": {
        "type": "account",
        "id": "10001"
      }
    },
    "customer": {
      "data": {
        "type": "customer",
        "id": "3"
      }
    }
  }
}

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 number The amount (cents) of the transaction. Common to all transaction types.
balance number 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

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

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"
  },
  "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 number The amount (cents) of the transaction. Common to all transaction types.
balance number 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
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

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

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 number The amount (cents) of the transaction. Common to all transaction types.
balance number 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

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

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

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)

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 number The amount (cents) of the transaction. Common to all transaction types.
balance number 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

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
    }
  },
  "relationships": {
    "account": {
      "data": {
        "type": "account",
        "id": "10001"
      }
    },
    "customer": {
      "data": {
        "type": "customer",
        "id": "3"
      }
    }
  }
}

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 number The amount (cents) of the transaction. Common to all transaction types.
balance number 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

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

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"
  },
  "relationships": {
    "account": {
      "data": {
        "type": "depositAccount",
        "id": "1000"
      }
    }
  }
}

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 number The amount (cents) of the transaction. Common to all transaction types.
balance number 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

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

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 number The amount (cents) of the transaction. Common to all transaction types.
balance number The account balance (cents) after the transaction. Common to all transaction types.
summary string Summary of the transaction. Common to all transaction types.

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 number The amount (cents) of the transaction. Common to all transaction types.
balance number 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.

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 number The amount (cents) of the transaction. Common to all transaction types.
balance number 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.

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

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-10",
    "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 (numbers only). 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 string e.g. "2001-08-10"
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-10",
    "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 (numbers only). 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 string e.g. "2001-08-10"
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 bussiness

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