Developer Integration Documentation

Introduction

Welcome to The Closing Docs! Here, you'll find documentation for our embedded income screening form, Paycheck, that simplifies and secures online automated income verification. Quickly integrate Paycheck into your software to provide landlords a streamlined, mobile-ready income verification experience that is constantly improving.

We've tried to make the this documentation user-friendly and example-filled, but if you have any questions, please don't hesitate to email us!


Integrating Paycheck

The easiest way to integrate The Closing Docs' income verification is to use Paycheck, an embedded tool that takes care of building an HTML form, validating bank credentials in a secure and compliant manner, and collecting and verifying income data.

Using Paycheck, sensitive bank credentials never touches your servers, allowing you to never deal with financial security or encryption.

To see Paycheck in action, click the button below. When you reach the bank integration, please:

  1. Click on the Wells Fargo financial institution.
  2. Login with the mock username user_good and the password pass_good.

Embedding Paycheck into your site

To get started, add the following code to the page where you wish to receive income data:

<script src="https://www.theclosingdocs.com/paycheck/beta/v1/paycheck.js"></script>

<button id="paycheck-button">Open Paycheck</button>

<script>
paycheck.create({
  publicKey: 'PUBLIC_KEY', // Replace PUBLIC_KEY with your own public key
  applicantName: 'Stevie Wonder',
  landlordName: 'Anthony Kiedis',
  env: 'sandbox',
  onSuccess: function(paycheck) {
    // Receive the Paycheck object here.
    // The paycheck object contains information
    // about the applicant's income, employment, and financials
  }
});

function onClick() {
  paycheck.open();
};

document.getElementById('paycheck-button').onclick=onClick
</script>

Our integration allows you to use any HTML element or Javascript event to trigger Paycheck. When your page loads, you should initialize the paycheck handler by using paycheck.create(). You can then call paycheck.open() on the handler in response to any event.

Configuration options

Customize the Paycheck experience for each applicant by using the following configuration options.

Required

publicKey Your publicKey. Since we are in beta, you can obtain this key by emailing us.
onSuccess The callback to invoke when the Paycheck income verification process is complete. The function expects one argument, the Paycheck object.
function(paycheck)
applicantName The applicant's full name
landlordName The landlord's full name
env The Closing Docs widget environment to verify income. For development or testing, use sandbox. For production, use production.

The onSuccess callback

The onSuccess callback should take one argument, the paycheck object. The paycheck object is a nested object containing all of the applicant's income information:

Paycheck object

income The applicant's verified income, represented by the Income object.
accounts An array of Account objects. This represents a list of bank accounts owned by the applicant with the bank login credentials he used.
identity The applicant's identity directly from the financial institution, represented by the Identity object. This can be used for identity validation. (Not always available).
startDate The beginning date of when we started collecting income information. The default amount of time is one year, but some financial institutions only allow several months of data.
endDate The end date of when we started collecting income information. This is the date of when the applicant verified his income.
reportUrl A url for a report that we create for you using the applicant's income information. To view a sample report, click here.

Example

{
  "income": {Income object},
  "accounts": [{Account object}],
  "identity": {Identity object},
  "startDate": "03/14/2016",
  "endDate": "03/14/2017",
  "reportUrl": "www.theclosingdocs.com/samples/report.pdf"
}

Item information

This section contains information about each financial object you will receive.

Income object

The Income gives detailed information about the applicant's income information from between the start date and end date provided.

grossIncome The total amount of income the applicant received. This is not the total amount of inflows. We make sure the credits are classified as recurring, stable income.
grossIncomeBeforeTax The grossIncome before taxes were applied.
netIncome The grossIncome, subtracted by all expense transactions that occurred within the timeframe.
grossMonthlyIncome The average total amount of monthly income from the last three months.
netIncomeLastMonth The end date of when we started collecting income information. This is the date of when the applicant verified his income.
incomeStreams An array of IncomeStream objects that represent each applicant's income stream.

Example

{
  "grossIncome": 120032.12,
  "grossIncomeBeforeTax": 132012.32,
  "netIncome": -2341.98,
  "grossMonthlyIncome": 4589.36,
  "netIncomeLastMonth": 198.64,
  "incomeStreams": [{IncomeStream object}]
}

Income Stream object

The IncomeStream object represents an individual income stream from an applicant. An applicant's bank account can have multiple income streams. Multiple income streams can occur when multiple sources of income are found. For example, a husband and wife that both produce income flowing into one account.

name The name of the income stream, as found on the applicant's bank statement.
monthlyIncome The average gross monthly income of the incomeStream.
startDate The start date for the income stream.
endDate The end date for the income stream. If the income stream is still ongoing, the endDate will be the current date (or the date that the applicant verified his income).
numOfDays The number of days in between the startDate and endDate.

Example

{
  "name": "Volkswagen Edipayment",
  "monthlyIncome": 2398.32,
  "startDate": "06/18/16",
  "endDate": "08/23/16",
  "numOfDays": 67
}

Account object

The Account object represents an applicant's banking account connected to the bank account he logged in with. There can be multiple bank accounts representing checking, savings, and credit accounts.

institutionName The name of the financial institution that the applicant logged into. This is also the financial institution that this bank account belongs to.
accountName The name of the Account, as named in the financial institution itself.
accountType The type of Account this Account object is. See the account types table below.
accountSubType The accountSubType of this Account object. The subtype is a more detailed look at the accountType. See the account subtypes table below.
currentBalance The currentBalance is the total amount of funds in the account.
availableBalance The availableBalance is the current balance less any outstanding holds or debits that have not yet posted to the account.

Note: Not all institutions calculate the available balance. When the available balance is unavailable from the financial institution, The Closing Docs will return an available balance value of null.
balanceLimit The spending limit for credit accounts. For account types that do not apply, this attribute will be null.
last4Digits The last four digits of the Account's number, given by the financial institution.

Account types

The available accountType's from the Account object.

depository Checking or savings accounts
credit Credit card account
loan Loan account
mortgage Mortgage account
brokerage Brokerage account
other Non-specified account type

Account Subtypes

The available accountSubtype's from the Account object.

depository checking, savings, money market, paypal, prepaid
credit credit card, paypal, line of credit, rewards
loan auto, commercial, construction, consumer, home, home equity, loan, mortgage, overdraft, line of credit, student
mortgage home
brokerage 401k, brokerage, ira, retirement, roth, ugma
other 403B, cash management, cd, hsa, keogh, money market, mutual fund, prepaid, recurring, rewards, safe deposit, sarsep, other

Example

{
  "institutionName": "Chase Bank",
  "accountName": "Frank College Checking Account",
  "accountType": "depository",
  "accountSubtype": "checking",
  "currentBalance": 3021.56,
  "availableBalance": 3021.56,
  "balanceLimit": null,
  "last4Digits": "1234"
}

Identity object

The Identity object contains information about the applicant as seen within the financial institution. Not every financial institution supports the Identity object. If the applicant's financial institution does not support the Identity, the identity attribute in the Paycheck object will be null. Depending on the financial institution, some attributes in the Identity object are not available, and will return null.

fullName The full name of the applicant.
address The address of the applicant as recorded from their financial institution.
city The applicant's city.
state The applicant's state.
zipCode The applicant's zip code.
email The applicant's email from their financial institution.
phoneNumber The applicant's phone number.

Example

{
  "fullName": "Bruce Wayne",
  "address": "1234 Batcave Manor Dr.",
  "city": "Goutham City",
  "state	": "TX",
  "zipCode": "75092",
  "email": "notbatman@email.com",
  "phoneNumber": 2145623445
}

API

Here, you'll find documentation of our API endpoints. Our API is only available once you have created a Paycheck object through our integration widget.

A clientId and a secretKey are both required to use our API. Both keys need to be attached to all requests to the API. You can ask for these keys by emailing support@theclosingdocs.com.

Retrieve Paycheck Object

The GET /api/v1/paycheck/{paycheck_id} endpoint returns the Paycheck object of a specified id. We recommend using this endpoint instead of storing sensitive financial information on your servers.

client_id Required. Your clientId provided to you.
secret_key Required. You secretKey provided to you.

Example

curl -X GET "https://www.theclosingdocs.com/api/v1/paycheck/{paycheck_id}?client_id={client_id}&secret_key={secret_key}"