Download Postman

Introduction Last updated: 2021-06-23

You can integrate your product or custom application with Flashspread to:
  • Upload documents
  • Monitor the status of a spread
  • Retrieve spread data
  • Run reports
There are two ways to integrate with Flashspread:
  • Call our API
  • Show our Widget in an iFrame
You can use both at the same time.

API Basics

Our API follows the REST model with all API calls sent over HTTPS to sub-paths of:

https://api.flashspread.com/api/{version}

Available versions

API calls must be authenticated. To authenticate, you:
  1. Obtain your Api Export Key:
    1. Log into Flashspread
    2. Click on your name in the top-right
    3. Select Profile
  2. Call the "Sign In" API method to exchange your Api Export Key for an Access Token.
  3. Send the Access Token in the Authorization header for all future API calls.

API Calls

The calls available from the Flashspread API are:
Sign In Exchange your Api Export Key for an access token
Upload Documents Upload new documents to be spread
Export Document Data Download spread documents
Retrieve Tax Forms Data Download spread tax forms
Retrieve Tax Forms Data (mapped) Download mapped spread tax forms
List Available Reports Retrieve a list of all reports the user can run
Get a Report Run one report
Query Reports Run multiple reports
Get a Report (Excel) Run one report (Excel)
Query Reports Run multiple reports (Zip of Excels)
List Available Deals Retrieve a list of all deals the user can run
Add a Deal Add a new Deal
Get a Deal Run one deal
Get a Deal (Excel) Run one deal (Excel)
Add Debt Schedule Data Push new Debt Schedule record
Update Debt Schedule Record Update Debt Schedule record
Delete Debt Schedule Record Delete Debt Schedule record
Retrieve Debt Schedule Data Get Debt Schedule records
Add loan (Report) Add new loan record for Report
Add loan (Deal) Add new loan record for Deal
Get a Deal Run one deal
Retrieve Business Rules Retrieve business rules
Add Borrower to Deal Add Borrower to Deal
Update Borrower Type Update Borrower Type
Remove Borrower from Deal Remove Borrower from Deal
Edit Deal Edit Deal
Apply Business Rules on Deal Apply Business Rules on Deal
Validate Widget Token Validate Widget Token
Create Entity Create Entity
Create Individual Create Individual

Each of these API calls is explained in detail below.

APIs

Sign In

To obtain an Access Token in order to use other API calls, you must sign in:

POST /sign_in

Headers

  • Content-type: application/json


Request Content

The request content should be a JSON object with one field:

security_key String
Required		 The "Api Export Key" will be emailed to you by a member of the FlashSpread support team

Response

If it succeeds, the content returned will be a JSON object containing the following fields:

email String Your email address
full_name String Your full name
tenant_name String The name of your Flashspread tenant
access_level String Your access level
access_token String The access token that you will use to authorize yourself for all other API calls.

Upload Documents

To upload new tax forms to FlashSpread, you use call:

POST /document

Headers

  • Content-type: multipart/form-data
  • Authorization: {Your access token}


Request Content

The following fields are sent as form data. Where <form> appears, it may be one of: main, schedule_c, schedule_f, or schedule_k.

files[] Binary file dataRequired Array of files that you want to spread.
additional_ein[<form>] Object String in "##-#######" format; optional. Specifies an additional EIN to associate with the named form. May be repeated more than once with different <form>.
additional_ssn[<form>] Object String in "###-##-####" format; optional. Specifies an additional SSN to associate with the named form. May be repeated more than once with different <form>.
user_year Four-digit integer Specifies a tax year to associate with the named form. May be repeated more than once with different <form>.
callback_url String A URL that Flashspread will call when the documents' status changes. See _____.
deal_identifier String A Deal identifier that Flashspread will use to create a deal
borrower_type String The one value from the list (affiliate, subject_entity, guarantor)

Response

If it succeeds, the content returned will be a JSON array containing one object for each file uploaded. Each object will contain the following fields:

name String The name of the file
status String One of the Document Status values. (See below)
created_at String in YYYY-MM-DDThh:mm:ss.sTZ format. The date the file was uploaded.
id Integer The document's id
validation_status String One of the Document Status values.

Retrieve Document Data

To download the data for all of a document's forms, call:

GET document/tax_forms?document_id=:document_id

Headers

  • Authorization: {Your access token}

Query Params

document_id Integer
Required		 The docuent's id (retured when it was uploaded)

Response

If it succeeds, the content returned will be a JSON object containing these properties:

document_id Integer The id of the document
status String Document status (see Codes section below)
schedules Object An array of Schedule objects. (See below)
forms Object An array of Form objects. (See below)

Retrieve Tax Forms Data

To download the one or more tax forms, call:

GET /tax_forms

Headers

  • Authorization: {Your access token}
  • Content-type: application/json

Query Parameters

The call may include zero or more of the following query string parameters. They will be used to filter the results.

deal_id String The deal id provided during upload
ein String The document's EIN
ssn String The document's SSN
year Integer The document's tax year
field_value_format String The format for form and schedule field value. Available formats: 'units', 'thousands'.
If not specified the 'units' is used by default.

Request Content

The request content empty.

Response

If it succeeds, the content returned will be a JSON object containing two properties:

schedules Array of Object An array of Form objects. (See Data Objects below)
forms Array of Object An array of Schedule objects. (See Data Objects below)

Retrieve Tax Forms Data (mapped)

To download the one or more tax forms, call:

GET /mapped/tax_forms

Headers

  • Authorization: {Your access token}
  • Content-type: application/json

Query Parameters

The call may include zero or more of the following query string parameters. They will be used to filter the results.

deal_id String The deal id provided during upload
ein String The document's EIN
ssn String The document's SSN
year Integer The document's tax year
field_value_format String The format for form and schedule field value. Available formats: 'units', 'thousands'.
If not specified the 'units' is used by default.

Request Content

The request content empty.

Response

If it succeeds, the content returned will be a JSON object containing two properties:

schedules Array of Object An array of Form objects. (See Data Objects below)
forms Array of Object An array of Schedule objects. (See Data Objects below)

List Available Reports

To get a list of all reports the user is allowed to run, call:

GET /labels/reports

Headers

  • Authorization: {Your access token}

Request Content

The request content should be empty.

Response

If it succeeds, the content returned will be a JSON array containing zero or more objects. Each object will have these properties:

label String Internal name of the report
name String User-friendly name of the report
cast String Report category: entity, individual, or global

Get a Report

To get a report, call::

GET /reports/:report_label

Headers

  • Authorization: {Your access token}

Path Parameters

report_label String Internal name of the report, matching one of the labels returned by List Available Reports.

Query Parameters

The call should include the following as a query string parameter:

code String
Required		 A SSN or EIN. Report will be retrieved for the matching individual or entity.

Request Content

The request content should be a JSON object containing the following fields:

Response

If it succeeds, the content returned will be a Report JSON object. (See Data Objects section.)

Query Reports

To get a multiple reports at once, call:

GET /reports/

Headers

  • Authorization: {Your access token}

Query Parameters

The call should include both of these query string parameters. They will be used to filter the results.

code String
Required		 A SSN or EIN. Report will be retrieved for the matching individual or entity.
labels Array of String
Required		 Internal names of the reports, matching one of the labels returned by List Available Reports.

Request Content

The request content should be empty.

Response

If it succeeds, the content returned will be a Array of Report JSON object. (See Data Objects section.)

Get a Report (Excel)

To get a report, call:

GET /reports/:report_label/excel

Headers

  • Authorization: {Your access token}

Path Parameters

report_label String Internal name of the report, matching one of the labels returned by List Available Reports.

Query Parameters

The call should include the following as a query string parameter:

code String
Required		 A SSN or EIN. Report will be retrieved for the matching individual or entity.

Request Content

The request content should be a JSON object containing the following fields:

Response

If it succeeds, the content returned will be a Excel file

Query Reports (Zip of Excels)

To get a multiple Excel's reports at once in Zip, call:

GET /reports/excel

Headers

  • Authorization: {Your access token}

Query Parameters

The call should include both of these query string parameters. They will be used to filter the results.

code String
Required		 A SSN or EIN. Report will be retrieved for the matching individual or entity.
labels Array of String
Required		 Internal names of the reports, matching one of the labels returned by List Available Reports.

Request Content

The request content should be empty.

Response

If it succeeds, the content returned will be a JSON object with each property being the name of a report and the value the Report object for that report. (See Data Objects section.)

List Available Deals

To get a list of all available deals, call:

GET /deals

Headers

  • Authorization: {Your access token}

Request Content

The request content should be empty.

Response

If it succeeds, the content returned will be a JSON array containing zero or more objects. Each object will have these properties:

name String User-friendly name of the deal
deal_id String Deal Id
tax_year_start Integer Deal start period
tax_year_end Integer Deal end period

Add a Deal

To add a new Deal, call:

POST /deals

Headers

  • Authorization: {Your access token}

Request Content

The request content should be a JSON object with the next available fields:

name String User-friendly name of the deal
deal_id String Internal name of the deal
tax_year_start Integer Deal start period
tax_year_end Integer Deal end period
report_label String Internal name of the report, matching one of the labels returned by List Available Reports.
borrowers Array of Object An array of Borrowers, the borrower object should have the same fields as in Add Borrower to Deal request - code, type, borrower_type

Response

If it succeeds, the content returned will be a JSON object with the next available fields:

deal_id String Internal name of the deal, matching one of the deal_id returned by List Available Deals.
entities Array of Object An array of Deal Entity object related to deal_id
individuals Array of Object An array of Deal Individual object related to deal_id
Response Example:
                  
                    {
                      "deal_id": "test_deal",
                      "entities": [
                          {
                              "id": 808,
                              "name": "Green Belt Carwash LLC",
                              "ein": "00-0000000",
                              "borrower_type": "subject_entity"
                          }
                      ],
                      "individuals": [
                          {
                              "id": 996,
                              "name": null,
                              "ssn": "000-00-0000",
                              "borrower_type": "guarantor"
                          }
                      ]
                    }

Get a Deal

To get the data for a deal, call:

GET /deals/:deal_id

Headers

  • Authorization: {Your access token}

Path Parameters

deal_id String Internal name of the deal, matching one of the deal_id returned by List Available Deals.

Response

If it succeeds, the content returned will be a Deal object. (See Data Objects section.)

Get a Deal (Excel)

To get the data for a deal, call:

GET /deals/:deal_id/excel

Headers

  • Authorization: {Your access token}

Path Parameters

deal_id String Internal name of the deal, matching one of the deal_id returned by List Available Deals.

Response

If it succeeds, the content returned will be a Excel file

Add Debt Schedule Data

To add new debt schedule record to FlashSpread, you use call:

POST /debt_schedules

Headers

  • Authorization: {Your access token}


Request Content

The request content should be a JSON object with the next available field:

ssn String The owner's SSN
ein String The owner's EIN
lender String Lender info
original_amount Integer Original amount
original_date String in YYYY-MM-DDThh:mm:ss.sTZ format. Original date
balance_due Integer Balance Due
interest_rate Float number Interest Rate
maturity_date String in YYYY-MM-DDThh:mm:ss.sTZ format. Maturity Date
monthly_payment Integer Monthly Payment
annual_payment Integer Annual Payment
notes String Notes

Response

If it succeeds, the content returned will be a Debt Schedule JSON object. (See Data Objects below)

Update Debt Schedule Record

To update debt schedule record, you use call:

PUT /debt_schedules/:id

Headers

  • Authorization: {Your access token}

Path Parameters

id String Identifier of created debt schedule record


Request Content

The request content should be a JSON object with the next available field:

lender String Lender info
original_amount Integer Original amount
original_date String in YYYY-MM-DDThh:mm:ss.sTZ format. Original date
balance_due Integer Balance Due
interest_rate Float number Interest Rate
maturity_date String in YYYY-MM-DDThh:mm:ss.sTZ format. Maturity Date
monthly_payment Integer Monthly Payment
annual_payment Integer Annual Payment
notes String Notes

Response

If it succeeds, the content returned will be a Debt Schedule JSON object. (See Data Objects below)

Delete Debt Schedule Record

To delete already created Debt Schedule Record, you can use call:

DELETE /debt_schedules/:id

Headers

  • Authorization: {Your access token}

Path Parameters

id String Identifier of created debt schedule record

Retrieve Debt Schedule Data

To get a Debt Schedule data, call:

GET /debt_schedules

Headers

  • Authorization: {Your access token}


Request Content

The request content should be a JSON object with the next available field:

ssn String The owner's SSN
ein String The owner's EIN

Response

If it succeeds, the content returned will be a JSON object containing the following fields:

schedules Array of Object An array of Debt Schedule objects. (See Data Objects below)
total Object Present original_amount, balance_due, monthly_payment and annual_payment totals

Add Loan (Report)

To add new loan record to Report, you use call:

POST /payment_calculations

Headers

  • Authorization: {Your access token}


Request Content

The request content should be a JSON object with the next available field:

ssn String
Required		 The owner's SSN
ein String
Required		 The owner's EIN
report_label String
Required		 The Report label
loan_type String
Required		 The one value from the list (amortized, interest_only, flat_fee)
monthly_payment Integer Monthly Payment
annual_payment Integer Annual Payment
prepayment_penalty Integer Prepayment Penalty
referral_source Integer Referral Source
interest_rate Integer Interest Rate
loan_amount Integer Loan amount
loan_name String The tag/name for this loan

Response

If it succeeds, the content returned will be a JSON object containing the following fields:

id Integer Loan identifier
monthly_payment Integer An array of Debt Schedule objects. (See Data Objects below)
annual_payment Integer Present original_amount, balance_due, monthly_payment and annual_payment totals
prepayment_penalty Integer An array of Debt Schedule objects. (See Data Objects below)
referral_source Integer An array of Debt Schedule objects. (See Data Objects below)
interest_rate Integer An array of Debt Schedule objects. (See Data Objects below)
loan_type Integer An array of Debt Schedule objects. (See Data Objects below)
loan_amount Integer Loan amount
loan_name String The tag/name for this loan

Add Loan (Deal)

To add new loan record to Deal, you use call:

POST /deals/:deal_id/payment_calculations

Path Parameters

deal_id String Internal name of the deal, matching one of the deal_id returned by List Available Deals.

Headers

  • Authorization: {Your access token}


Request Content

The request content should be a JSON object with the next available field:

loan_type String
Required		 The one value from the list (amortized, interest_only, flat_fee)
monthly_payment Integer Monthly Payment
annual_payment Integer Annual Payment
prepayment_penalty Integer Prepayment Penalty
referral_source Integer Referral Source
interest_rate Integer Interest Rate
loan_amount Integer Loan amount
loan_name String The tag/name for this loan

Response

If it succeeds, the content returned will be a JSON object containing the following fields:

id Integer Loan identifier
monthly_payment Integer An array of Debt Schedule objects. (See Data Objects below)
annual_payment Integer Present original_amount, balance_due, monthly_payment and annual_payment totals
prepayment_penalty Integer An array of Debt Schedule objects. (See Data Objects below)
referral_source Integer An array of Debt Schedule objects. (See Data Objects below)
interest_rate Integer An array of Debt Schedule objects. (See Data Objects below)
loan_type Integer An array of Debt Schedule objects. (See Data Objects below)
loan_amount Integer Loan amount
loan_name String The tag/name for this loan

Retrieve Loan Data (Report)

To get a Loans data, call:

GET /payment_calculations

Headers

  • Authorization: {Your access token}


Request Content

The request content should be a JSON object with the next available field:

ssn String
Required		 The owner's SSN
ein String
Required		 The owner's EIN
report_label String
Required		 The Report label

Response

If it succeeds, the content returned will be Loan object. (See below)

Retrieve Loan Data (Deal)

To get a Loans data, call:

GET deals/:deal_id/payment_calculations

Path Parameters

deal_id String Internal name of the deal, matching one of the deal_id returned by List Available Deals.

Headers

  • Authorization: {Your access token}


Response

If it succeeds, the content returned will be an array of Loan objects. (See below)

Response Example:
                
                  [
                    {
                        "id": 103,
                        "monthly_payment": 13,
                        "annual_payment": 166,
                        "prepayment_penalty": null,
                        "referral_source": null,
                        "interest_rate": "3.0",
                        "term_months": 9,
                        "loan_type": "amortized",
                        "loan_amount": 123,
                        "loan_name": "Test loan"
                    },
                    {
                        "id": 135,
                        "monthly_payment": 42,
                        "annual_payment": 505,
                        "prepayment_penalty": null,
                        "referral_source": null,
                        "interest_rate": "3.0",
                        "term_months": 8,
                        "loan_type": "amortized",
                        "loan_amount": 333,
                        "loan_name": "Loan for Deal"
                    }
                ]

Update Loan

To update already created Loan, you can use call:

PUT /payment_calculations/:loan_id

Path Parameters

loan_id Integer Loan identifier

Headers

  • Authorization: {Your access token}


Response

If it succeeds, the content returned will be a JSON object containing the following fields:

id Integer Loan identifier
monthly_payment Integer Monthly Payment
annual_payment Integer Annual Payment
prepayment_penalty Integer Prepayment Penalty
referral_source Integer Referral Source
interest_rate Integer Interest Rate
loan_type Integer Loan type. The one value from the list (amortized, interest_only, flat_fee)
loan_amount Integer Loan amount
loan_name String The tag/name for this loan

Delete Loan

To delete already created Loan, you can use call:

DELETE /payment_calculations/:loan_id

Path Parameters

loan_id Integer Loan identifier

Headers

  • Authorization: {Your access token}

Retrieve Business Rules

There are 3 endpoints to get business rules:

Deal Business Rules

GET deals/:deal_identifier/business_rules

Headers

  • Authorization: {Your access token}

Path Parameters

deal_identifier String Name of a deal identifier attached to document.

Entity or Individual Business Rules

GET owners/:code/business_rules

Headers

  • Authorization: {Your access token}

Path Parameters

code String EIN (Entity) or SSN (Individual).

Tax Form Business Rules

GET tax_forms/business_rules?objectable_id={objectable_id}&objectable_type={objectable_type}

Headers

  • Authorization: {Your access token}

Path Parameters

code String EIN (Entity) or SSN (Individual).
objectable_id String Tax form internal id.
objectable_type String Type of tax form (See the Data objects -> Form section).

Response

If it succeeds, the content returned will be a BusinessRule object. (See Data Objects section.)

Add Borrower to Deal

To add existed borrower to deal, call:

POST /deals/:deal_id/borrowers

Headers

  • Authorization: {Your access token}

Path Parameters

deal_id String Internal name of the deal, matching one of the deal_id returned by List Available Deals.


Request Content

The request content should be a JSON object with the next available field:

code String
Required		 A SSN or EIN. Will use this code for the matching individual or entity and add them to deal.
type String
Required		 Code type. The one value from the list (Entity, Individual)
borrower_type String
Required		 The one value from the list (affiliate, subject_entity, guarantor)

Response

If it succeeds, the content returned will be an array of Loan objects. (See below)

deal_id String Internal name of the deal, matching one of the deal_id returned by List Available Deals.
entities Array of Object An array of Deal Entity object related to deal_id
individuals Array of Object An array of Deal Individual object related to deal_id
Response Example:
                  
                    {
                      "deal_id": "test_deal",
                      "entities": [
                          {
                              "id": 808,
                              "name": "Green Belt Carwash LLC",
                              "ein": "00-0000000",
                              "borrower_type": "subject_entity"
                          }
                      ],
                      "individuals": [
                          {
                              "id": 996,
                              "name": null,
                              "ssn": "000-00-0000",
                              "borrower_type": "guarantor"
                          }
                      ]
                    }

Update Borrower Type

To update existed borrower type, call:

PATCH /deals/:deal_id/borrowers

Headers

  • Authorization: {Your access token}

Path Parameters

deal_id String Internal name of the deal, matching one of the deal_id returned by List Available Deals.


Request Content

The request content should be a JSON object with the next available field:

code String
Required		 A SSN or EIN. Will use this code for the matching individual or entity and add them to deal.
type String
Required		 Code type. The one value from the list (Entity, Individual)
borrower_type String
Required		 The one value from the list (affiliate, subject_entity, guarantor)

Response

If it succeeds, the content returned will be an array of Loan objects. (See below)

deal_id String Internal name of the deal, matching one of the deal_id returned by List Available Deals.
entities Array of Object An array of Deal Entity object related to deal_id
individuals Array of Object An array of Deal Individual object related to deal_id
Response Example:
                  
                    {
                      "deal_id": "test_deal",
                      "entities": [
                          {
                              "id": 808,
                              "name": "Green Belt Carwash LLC",
                              "ein": "00-0000000",
                              "borrower_type": "subject_entity"
                          }
                      ],
                      "individuals": [
                          {
                              "id": 996,
                              "name": null,
                              "ssn": "000-00-0000",
                              "borrower_type": "guarantor"
                          }
                      ]
                    }

Remove Borrower from Deal

To remove existed borrower from deal, call:

DELETE /deals/:deal_id/borrowers

Headers

  • Authorization: {Your access token}

Path Parameters

deal_id String Internal name of the deal, matching one of the deal_id returned by List Available Deals.


Request Content

The request content should be a JSON object with the next available field:

code String
Required		 A SSN or EIN. Will use this code for the matching individual or entity and add them to deal.
type String
Required		 Code type. The one value from the list (Entity, Individual)

Response

If it succeeds, the content returned will be a JSON object with the next available field:

deal_id String Internal name of the deal, matching one of the deal_id returned by List Available Deals.
entities Array of Object An array of Deal Entity object related to this deal_id
individuals Array of Object An array of Deal Individual object related to this deal_id
Response Example:
                  
                    {
                      "deal_id": "test_deal",
                      "entities": [
                          {
                              "id": 808,
                              "name": "Green Belt Carwash LLC",
                              "ein": "00-0000000",
                              "borrower_type": "subject_entity"
                          }
                      ],
                      "individuals": [
                          {
                              "id": 996,
                              "name": null,
                              "ssn": "000-00-0000",
                              "borrower_type": "guarantor"
                          }
                      ]
                    }

Edit Deal

To edit deal, call:

PUT /deals/:deal_id

Headers

  • Authorization: {Your access token}

Path Parameters

deal_id String Internal name of the deal, matching one of the deal_id returned by List Available Deals.


Request Content

The request content should be a JSON object with the next available field:

last_tax_year_start Integer
 Deal start year
last_tax_year_end Integer
 Deal end year
name String
 Name of the deal
deal_type String
 Name of the deal type. To get available deal's types please reach to support team

Response

If it succeeds, the content returned will be a JSON object with the next available field:

deal_id String Internal name of the deal, matching one of the deal_id returned by List Available Deals.
name String Name of the deal
last_tax_year_start Integer Deal start year
last_tax_year_end Integer Deal end year
deal_type String Name of the deal type
Response Example:
                  
                    {
                      "deal_id": "86b3f876-73d9-4c44-b9c1-63b83c8d2c17",
                      "name": "Deal 1",
                      "last_tax_year_start": 2017,
                      "last_tax_year_end": 2021,
                      "deal_type": "Deal Type 1"
                    }

Apply Business Rules on Deal

To apply business rules on deal, call:

POST /deals/:deal_id/business_rules

Headers

  • Authorization: {Your access token}

Path Parameters

deal_id String Internal name of the deal, matching one of the deal_id returned by List Available Deals.


Response

If it succeeds, the content returned will be a array ofJSON Business rule objects

Response Example:
                  
                    [
                      {
                          "id": 41,
                          "explanation": 'The Gross receipts or sales of current year must be less than the previous year',
                          "status": "pending",
                          "corrective_action": null,
                          "updated_at": "2022-07-08T14:25:41.942Z",
                          "form_id": null,
                          "description": "The Gross receipts or sales of current year should always be less than the Gross receipts or sales of previous year",
                          "updated_by": "John Smit"
                      }
                    ]

Validate Widget Token

To validate your widget token, call:

POST /validate_widget_token

token String Widget Token

Response

If it succeeds, it will return 200 status.

Create Entity

To create a new Entity, call:

POST /entities

Headers

  • Authorization: {Your access token}

Request Content

The request content should be a JSON object with the next available fields:

ein String
Required		 String in ##-####### format. The entity's EIN
name String Entity's name
address_1 String Entity's address_1
address_2 String Entity's address_2
city String Entity's city
state String Entity's state
zip String Entity's zip
business_code String Entity's business code
active boolean The flag, that show status of entity (active or doesn't active)

Response

Response Example:
                  
                    {
                        "name": "Flashspread Company",
                        "id": 2175,
                        "address_1": "303 W Inyokern Rd",
                        "address_2": "",
                        "city": "Ridgecrest",
                        "state": "CA",
                        "zip": "93555",
                        "business_code": "112110",
                        "active": true
                    }

Create Individual

To create a new Individual, call:

POST /individuals

Headers

  • Authorization: {Your access token}

Request Content

The request content should be a JSON object with the next available fields:

ssn String
Required		 String in ###-##-#### format. The individual's SSN
name String Individual's name
address_1 String Individual's address_1
address_2 String Individual's address_2
city String Individual's city
state String Individual's state
zip String Individual's zip
active boolean The flag, that show status of individual (active or doesn't active)

Response

Response Example:
                  
                    {
                        "id": 2177,
                        "ssn": "123-12-1235",
                        "name": "Denis Jons",
                        "address_1": "303 W Inyokern Rd",
                        "address_2": "",
                        "city": "Ridgecrest",
                        "state": "CA",
                        "zip": "93555",
                        "active": true
                    }

Retrieve Personal Financial Statement

To get a Personal Financials data, call:

GET /personal_financial_statement

Headers

  • Authorization: {Your access token}

Request Content

The request content should be a JSON object with the next available fields:

ssn String
Required		 String in ###-##-#### format. The individual's SSN

Response

If it succeeds, the content returned will be Personal Financials Statement object. (See below)

Create or Update Personal Financial Statement

To create or update a Personal Financials Statement, call:

PUT /personal_financial_statement

Headers

  • Authorization: {Your access token}

Request Content

The request content should be a JSON object with the next available fields and fields from Personal Financials Statement object body. :

ssn String
Required		 String in ###-##-#### format. The individual's SSN
description String Description

Response

If it succeeds, the content returned will be Personal Financials Statement object. (See below)

APIs V2

Get a Report

To get a report, call:

GET /reports/:report_label

Headers

  • Authorization: {Your access token}

Path Parameters

report_label String Internal name of the report, matching one of the labels returned by List Available Reports.

Query Parameters

The call should include the following as a query string parameter:

code String
Required		 A SSN or EIN. Report will be retrieved for the matching individual or entity.

Request Content

The request content should be empty.

Response

If it succeeds, the content returned will be a Report JSON object. (See Data Objects section.)

Get a Report Structure

To get a report structure, call:

GET /reports/:report_label/structure

Headers

  • Authorization: {Your access token}

Path Parameters

report_label String Internal name of the report, matching one of the labels returned by List Available Reports.

Query Parameters

The call should include the following as a query string parameter:

code String
Required		 A SSN or EIN. Report will be retrieved for the matching individual or entity.

Request Content

The request content should be empty.

Response

If it succeeds, the content returned will be a Report JSON object with the Sections array instead of Rows array. Section object contains title of the section and rows array. Each row has a label from data dictionary and key/value pairs where key - year, value - Form Field value.

Sample:
                  
                    {
                      "forms":[
                        {
                            "id":8281,
                            "year":2013,
                            "month":12,
                            "period_begin_date": "01/01/2023",
                            "period_end_date": "12/31/2023"
                        },
                        {
                            "id":8291,
                            "year":2014,
                            "month":12,
                            "period_begin_date": "01/01/2024",
                            "period_end_date": "12/31/2024"
                        },
                      ],
                      "payment_calculator": {
                        monthly_payment: 100,
                        annual_payment: 1200,
                        prepayment_penalty:  '12/31/23',
                        referral_source:  null,
                        interest_rate:  0,
                        term_months:  12,
                        loan_type: "amortized",
                        loan_amount: 0
                      },
                      "sections":[
                        {
                          "title": "Income",
                          "rows": {
                              "Gross Reciepts or Sales": [
                                  {
                                      "2013": 683340.0,
                                      "2014": 0.0,
                                      "label": "gross_sales"
                                  },
                                  {
                                      "2013": 100.0,
                                      "2014": 5.5,
                                      "label": "gross_sales_cs"
                                  }
                              ],
                              "Returns and Allowances": [
                                  {
                                      "2013": 0.0,
                                      "2014": 0.0,
                                      "label": "returns_allowances"
                                  },
                                  {
                                      "2013": 0.0,
                                      "2014": 0.0,
                                      "label": "returns_allowances_cs"
                                  }
                              ],
                        },
                        ...
                      ]
                    }

Query Reports

To get a multiple reports at once, call:

GET /reports/

Headers

  • Authorization: {Your access token}

Query Parameters

The call should include both of these query string parameters. They will be used to filter the results.

code String
Required		 A SSN or EIN. Report will be retrieved for the matching individual or entity.
labels Array of String
Required		 Internal names of the reports, matching one of the labels returned by List Available Reports.

Request Content

The request content should be empty.

Response

If it succeeds, the content returned will be a Array of Report JSON object. (See Data Objects section.)

Get a Borrower

Starting from v2 API provide the endpoint to get the Borrower's data and its tax forms with financials:

GET /borrower?tin=:tin&type=:type

Headers

  • Authorization: {Your access token}
  • Content-type: application/json

Query Parameters

The call should include the following query string parameters.

tin String
Required		 The borrower's EIN/SSN
type String
Required		 Type of borrower. Available types: Entity, Individual

Request Content

The request content empty.

Response

If it succeeds, the content returned will be the Borrower JSON object (See Data Objects below).

Query Reports (in one excel file)

To get a multiple Excel's reports at once in one excel file, call:

GET /reports/excel

Headers

  • Authorization: {Your access token}

Query Parameters

The call should include both of these query string parameters. They will be used to filter the results.

code String
Required		 A SSN or EIN. Report will be retrieved for the matching individual or entity.
labels Array of String
Required		 Internal names of the reports, matching one of the labels returned by List Available Reports.

Request Content

The request content should be empty.

Response

If it succeeds, the content returned will be a Excel file with each tab being the name of a report.

Get Deal Owner Reports

To get multiple reports for each deal owner, call:

GET /deals/:deal_id/reports

Headers

  • Authorization: {Your access token}

Query Parameters

The call should include this query string parameter. It will be used to find the corresponding deal.

deal_id String
Required		 A Deal identifier that Flashspread uses to create a deal

Request Content

The request content should be empty.

Response

If it succeeds, the content returned will be an object with SSNs and EINs as keys and Report objects as values.

Example:
                  
                    {
                      "507-54-7635": {
                          "default_individual_032023": {
                              "forms": [
                                  {
                                      "id": 10581,
                                      "year": 2021,
                                      "months": 12,
                                      "period_begin_date": "01/01/2021",
                                      "period_end_date": "12/31/2021"
                                  }
                              ],
                              "rows": {
                                  "wages": {
                                      "10581": 0.0,
                                      "10582": 0.0
                                  },
                                  "interest_income": {
                                      "10581": 6.0,
                                      "10582": 75.0
                                  },
                                  "dividends": {
                                      "10581": 104.0,
                                      "10582": 0.0
                                  },
                              },
                              "payment_calculators": [
                                  {
                                      "monthly_payment": null,
                                      "annual_payment": null,
                                      "prepayment_penalty": null,
                                      "referral_source": null,
                                      "interest_rate": null,
                                      "term_months": null,
                                      "loan_type": "amortized",
                                      "loan_amount": null,
                                      "loan_name": "Flash Individual Cashflow 2.1",
                                      "id": 1349
                                  }
                              ],
                              "notes": []
                          }
                      },
                      }
                  }

Hooks

If you provided a callback_url when you uploaded documents, Flashspread will call that URL each time the status of one of the included documents changes. Flashspread will call:

POST The URL you provided

Headers

  • Content-type: application/JSON

Request Content

document_id Integer
Required		 The id of the document with the status change
event String
Required		 Reason of send hook, (see below Events table)
status String
Required		 Processing Document Status (see below)
validation_status String
Required		 Validation Status of document. (see below)
review_status String
Required		 Review Status of document. (see below)
schedules[] Object A schedule object, if you uploaded one without the main form, and if the data is available.
forms[] Object A form object if the data is available

Events

processing_status_changed Processing document status has been changed
review_status_changed Review document status has been changed
validation_status_changed Validation document status has been changed
owner_changed Owner of forms or schedules inside document has been changed
document_overrided Document has been overrided and was archived
Example:
                  
                    {
                      "status": "processing",
                      "event": "processing_status_changed",
                      "validation_status": null,
                      "review_status": null,
                      "document_id": "263"
                    }

Data Objects

The Flashspread API uses JSON objects to represent most data.

Form

A Form is a JSON object that represents a tax form. There are four types of Form object. All of them have these fields in common:

type String The form's type, one of:
  • Forms::Form1120S
  • Forms::Form1120
  • Forms::Form1065
  • Forms::Form1040
fields Object The object has one property for each field on the form that Flashspread was able to find with the value from the form. The complete list of fields can be found at _____.
statuses Object The object has one property for each field on the form. The property name is the field name and is value is the field status. The complete list of fields can be found at _____. The list of field statuses can be found below.
year Integer The form's tax year
document_id Integer Document identifier for this form
id Integer Form identifier
months Integer The form's tax year months
deductions Object he object has one property for each field on the form that Flashspread was able to find with the value from the form. The complete list of fields can be found at _____.
validation_status String Validation Status for For. (There are any issues on the form)
The one of:
  • no_errors
  • please_validate

Each form also has its own unique fields:


Form 1120S object

entity Entity object Form's Entity
form_1125_a Schedule object Form 1125A
form_8825 Schedule object Form 8825
schedule_b Schedule object 1120S Schedule B
schedule_k Schedule object 1120S Schedule K
schedule_k1 Array of Schedule's object 1120S Schedule k1
schedule_l Schedule object 1120S Schedule L
schedule_m1 Schedule object 1120S Schedule M1
schedule_m2 Schedule object 1120S Schedule M2

Form 1120 object

entity Entity object Form's Entity
form_1125_a Schedule object Form 1125A
schedule_k Schedule object 1120 Schedule K
schedule_l Schedule object 1120 Schedule L
schedule_m1 Schedule object 1120 Schedule M1
schedule_m2 Schedule object 1120 Schedule M2

Form 1065 object

entity Entity object Form's Entity
form_1125_a Schedule object Form 1125A
form_8825 Schedule object Form 8825
schedule_k Schedule object 1065 Schedule K
schedule_k1 Array of Schedule's object 1065 Schedule k1
schedule_l Schedule object 1065 Schedule L
schedule_m1 Schedule object 1065 Schedule M1
schedule_m2 Schedule object 1065 Schedule M2

Form 1040 object

individual Individual object Form's Entity
form_4835 Schedule object Form 1125A
schedule_k1_1065 Array of Schedule's object 1065 Schedule k1
schedule_k1_1120s Array of Schedule's object 1120S Schedule k1
schedule_1 Schedule object 1040 Schedule 1
schedule_a Schedule object 1040 Schedule A
schedule_b Schedule object 1040 Schedule B
schedule_c Array of Schedule's object 1040 Schedule C
schedule_d Schedule object 1040 Schedule D
schedule_e Array of Schedule's object 1040 Schedule E
schedule_f Array of Schedule's object 1040 Schedule F

Schedule

A Schedule is a JSON object that represents a tax schedule. Schedule objects all have the same structure but will have different fields depending on their type.

type String The schedule's type. See below for the full list.
fields Object An object with one property for each field on the form that Flashspread was able to find. The property name is the field name and its value is the value. The complete list of fields can be found at _____.
statuses Object The object has one property for each field on the form. The property name is the field name and is value is the field status. The complete list of fields can be found at _____. The list of field statuses can be found below.
year Integer The schedule's tax year
document_id Integer The document identifier for this schedule
deductions Object Deduction object
validation_status String Validation Status for For. (There are any issues on the form)
The one of:
  • no_errors
  • please_validate

Schedule Types
Name Form Type
form_1125_a
  • 1065
  • 1120
  • 1120S
 Schedules::Form1125A
form_8825
  • 1065
  • 1120S
 Schedules::Form8825
schedule_b 1120S Schedules::Form1120S::ScheduleB
schedule_k 1120S Schedules::Form1120S::ScheduleK
schedule_k1 1120S SharedSchedules::Form1120S::ScheduleK1
schedule_l 1120S Schedules::Form1120S::ScheduleL
schedule_m1 1120S Schedules::Form1120S::ScheduleM1
schedule_m2 1120S Schedules::Form1120S::ScheduleM2
schedule_k 1120 Schedules::Form1120::ScheduleK
schedule_l 1120 Schedules::Form1120::ScheduleL
schedule_m1 1120 Schedules::Form1120::ScheduleM1
schedule_m2 1120 Schedules::Form1120::ScheduleM2
schedule_k 1065 Schedules::Form1065::ScheduleK
schedule_k1 1065 SharedSchedules::Form1065::ScheduleK1
schedule_l 1065 Schedules::Form1065::ScheduleL
schedule_m1 1065 Schedules::Form1065::ScheduleM1
schedule_m2 1065 Schedules::Form1065::ScheduleM2
form_4835 1040 Schedules::Form1040::Form4835
schedule_k1_1065 1040 SharedSchedules::Form1065::ScheduleK1
schedule_k1_1120s 1040 SharedSchedules::Form1120S::ScheduleK1
schedule_1 1040 Schedules::Form1040::Schedule1
schedule_a 1040 Schedules::Form1040::ScheduleA
schedule_b 1040 Schedules::Form1040::ScheduleB
schedule_c 1040 SharedSchedules::Form1040::ScheduleC
schedule_d 1040 Schedules::Form1040::ScheduleD
schedule_e 1040 Schedules::Form1040::ScheduleE
schedule_f 1040 SharedSchedules::Form1040::ScheduleF

Individual

An Individual is a JSON object that represents an individual person. Individual objects all have the same structure with the following fields:

ssn String String in ###-##-#### format. The individual's SSN.
name String Individual's name
city String Individual's city
address_1 String Individual's address_1
address_2 String Individual's address_2
state String Individual's state
zip String Individual's zip

Entity

An Entity is a JSON object that represents an entity. Individual objects all have the same structure with the following fields:

ein String String in ##-####### format. The entity's EIN
name String Entity's name
city String Entity's city
address_1 String Entity's address_1
address_2 String Entity's address_2
state String Entity's state
zip String Entity's zip

Report

A Report is a JSON object that represents the output from a report. It has these properties:

forms An array of objects, one for each column in the report. Each object has these fields:
id Id of document whose data is in the column
year Column's year
month Column's month
period_begin_date Report start period
period_end_date Report end period
rows An object that contains the report's data, with one property for each row of data in the report. The property's name is the field name. The full list of names can be found in the data dictionary in Flashspread.
The value of each property in "rows" is an object that itself contains value for this row and column. The property names matching the id field of this column from the forms array.
payment_calculator An object that contains the payment calculator data related to the report. The object has these fields:
monthly_payment Payment calculator value
annual_payment Payment calculator value
prepayment_penalty Payment calculator value
referral_source Payment calculator value
interest_rate Payment calculator value
term_months Payment calculator value
loan_type Payment calculator value
loan_amount Payment calculator value
notes An array of notes objects. Each object has these fields:
user_name Full name of the user that created a note
text Text of the note
Sample:
                
                  {
                    "forms":[
                       {
                          "id":8281,
                          "year":2013,
                          "month":12,
                          "period_begin_date": "01/01/2023",
                          "period_end_date": "12/31/2023"
                       },
                       {
                          "id":8291,
                          "year":2014,
                          "month":12,
                          "period_begin_date": "01/01/2024",
                          "period_end_date": "12/31/2024"
                       },
                    ],
                    "payment_calculator": {
                      monthly_payment: 100,
                      annual_payment: 1200,
                      prepayment_penalty:  '12/31/23',
                      referral_source:  null,
                      interest_rate:  0,
                      term_months:  12,
                      loan_type: "amortized",
                      loan_amount: 0
                    },
                    "rows":{
                       "cash":{
                          "8281": 124608,
                          "8291": 75063
                       },
                       "cash_cs":{
                          "8281": 0.09357139692525808,
                          "8291": 0.03835672577672331,
                       },
                       ...
                    },
                    "notes": [
                      {
                        "user_name": "James Martin",
                        "text": "example note"
                      },
                      ...
                    ]
                  }
Sample V2:

Please consider on key inside the field label. In v2 using year instead of id. 

                
                  {
                    "forms":[
                       {
                          "id":8281,
                          "year":2013,
                          "month":12,
                          "period_begin_date": "01/01/2023",
                          "period_end_date": "12/31/2023"
                       },
                       {
                          "id":8291,
                          "year":2014,
                          "month":12,
                          "period_begin_date": "01/01/2024",
                          "period_end_date": "12/31/2024"
                       },
                    ],
                    "payment_calculator": {
                      monthly_payment: 100,
                      annual_payment: 1200,
                      prepayment_penalty:  '12/31/23',
                      referral_source:  null,
                      interest_rate:  0,
                      term_months:  12,
                      loan_type: "amortized",
                      loan_amount: 0
                    },
                    "rows":{
                       "cash":{
                          "2013": 124608,
                          "2014": 75063
                       },
                       "cash_cs":{
                          "2013": 0.09357139692525808,
                          "2014": 0.03835672577672331,
                       },
                       ...
                    },
                    "notes": [
                      {
                        "user_name": "James Martin",
                        "text": "example note"
                      },
                      ...
                    ]
                  }

Debt Schedule

A Debt Schedule is a JSON object. It has these properties:

lender Lender
original_amount Original Amount
original_date Original Date
maturity_date Maturity Date
balance_due Balance Due
interest_rate Interest Rate
monthly_payment Monthly Payment
annual_payment Annual Payment
notes Notes
Sample:
                
                  {
                      "lender": "Lender",
                      "original_amount": 0,
                      "original_date": "07-07-2020",
                      "maturity_date": "07-07-2020",
                      "balance_due": 234,
                      "interest_rate": 2.34,
                      "monthly_payment": 234,
                      "annual_payment": 2808,
                      "notes": "Notes"
                  }

Deal

A Deal is a JSON object that represents the output from a deal. It has these properties:

years Years included in the deal
entities Entities included in the deal
individuals Individuals included in the deal
payment_calculator Payment calculations
rows Summary data
summary_rows Detail data
Sample:
                
                  {
                    {
                      "years": [
                          2018,
                          2019,
                          2020
                      ],
                      "entities": [
                          {
                              "id": 213,
                              "name": null,
                              "ein": "98-7654321"
                          },
                          {
                              "id": 781,
                              "name": "Flashspread Corp",
                              "ein": "98-7654322"
                          }
                      ],
                      "individuals": [
                          {
                              "id": 74,
                              "name": "JAMES E STALEY",
                              "ssn": "346-56-0000"
                          }
                      ],
                      "summary_rows": {
                          "individual_income_total_total": {
                              "2018": 0.0,
                              "2019": 0.0,
                              "2020": 0.0
                          },
                          "existing_debt_service_individuals": {
                              "2018": 0.0,
                              "2019": 0.0,
                              "2020": 0.0
                          },
                          "existing_debt_service_corporate_entities": {
                              "2018": 0.0,
                              "2019": 0.0,
                              "2020": 0.0
                          },
                          "existing_debt_service_eds": {
                              "2018": 0.0,
                              "2019": 0.0,
                              "2020": 0.0
                          },
                          "existing_debt_service_gds_cov_ratio": {
                              "2018": 0.0,
                              "2019": 0.0,
                              "2020": 0.0
                          }
                      },
                      "rows": {
                          "individual_income": {
                              "74": {
                                  "2018": null,
                                  "2019": null,
                                  "2020": null
                              }
                          },
                          "cash_flow_from_schedule_c": {
                              "74": {
                                  "2018": null,
                                  "2019": null,
                                  "2020": null
                              }
                          },
                          "ordinary_business_income": {
                              "213": {
                                  "2018": null,
                                  "2019": null,
                                  "2020": null
                              },
                              "781": {
                                  "2018": null,
                                  "2019": null,
                                  "2020": null
                              }
                          },
                          "total_depreciation": {
                              "213": {
                                  "2018": null,
                                  "2019": null,
                                  "2020": null
                              },
                              "781": {
                                  "2018": null,
                                  "2019": null,
                                  "2020": null
                              }
                          },
                          "income_total": {
                              "213": {
                                  "2018": null,
                                  "2019": null,
                                  "2020": null
                              },
                              "781": {
                                  "2018": null,
                                  "2019": null,
                                  "2020": null
                              }
                          },
                          "individual_income_total": {
                              "74": {
                                  "2018": null,
                                  "2019": null,
                                  "2020": null
                              }
                          },
                          "debt_service_liabilities": {
                              "74": {
                                  "2018": null,
                                  "2019": null,
                                  "2020": null
                              }
                          }
                      },
                      "payment_calculator": null
                    }
                  }

Loan

A Loan is a JSON object. It has these properties:

monthly_payment Monthly Payment
annual_payment Annual Payment
prepayment_penalty Prepayment Penalty
referral_source Referral Source
interest_rate Interest Rate
term_months Term Months
loan_type Loan Type
loan_amount Loan Amount
loan_name Loan Name
Sample:
                
                  {
                      "id": 26,
                      "monthly_payment": 10,
                      "annual_payment": 124,
                      "prepayment_penalty": 123,
                      "referral_source": null,
                      "interest_rate": "2.34",
                      "term_months": 12,
                      "loan_type": "amortized",
                      "loan_amount": 123,
                      "loan_name": "Test loan"
                  }

Business Rule

A Business Rule is a JSON object that represents the output from a Business Rule. It has these properties:

explanation Explanation of how the business rules was fixed
status The current business rule status. Available statuses:
  • fixed
  • pending
  • completed
  • reopened
corrective_action The corrective action for rule
description Business Rule description
updated_by The name and surname of user that updated the business rule
form_id Internal id of tax form the business rules is attached to
Sample:
                
                  {
                    "id": 82,
                    "explanation": '',
                    "status": "pending",
                    "corrective_action": null,
                    "updated_at": "2022-03-23T19:25:47.314Z",
                    "form_id": 272,
                    "description": "Form 1120S (gross_reciepts_sales) Current Year Greater 25 Current Year",
                    "updated_by": "flashspread user"
                  }

Unstructrured Document

An Unstructrured Document is a JSON object has the following structure:

id Integer
type String UnstructuredDocumet's type. Available types: UnstructuredDocuments::IncomeStatement, UnstructuredDocuments::BalanceSheet
entity_id Integer
document_id String
columns An array of objects. Each object has these fields:
id Integer
name String
date_from Date
date_to Date
rows An array of objects. Each object has these fields:
id Integer
name String
line_type String 'total', 'subtotal', 'line'
group_name String 'income', 'cost_of_goods_sold', 'expenses', 'other_income', 'other_expense', 'gross_profit', 'net_operation_income', 'net_income', 'ungrouped'
children An Array of Row children objects (self).
financial_category An array of objects. Each object has these fields:
id Integer
name String
row_values An array of objects. Each object has these fields:
id Integer
column_id Integer
value String
Sample:
                
                  {
                    "id": 162,
                    "type": "UnstructuredDocuments::IncomeStatement",
                    "entity_id": 533,
                    "document_id": 359,
                    "columns": [
                      {
                          "id": 171,
                          "name": null,
                          "year": 2019,
                          "date_from": "2019-01-01T00:00:00.000Z",
                          "date_to": "2019-07-31T00:00:00.000Z"
                      }
                    ],
                    rows: [
                      {
                        "id": 8364,
                        "name": "Other Income",
                        "line_type": "subtotal",
                        "group_name": "other_income",
                        "financial_category": null,
                        "children": [
                            {
                                "id": 8451,
                                "name": "Interest Income",
                                "line_type": "line",
                                "group_name": "other_income",
                                "financial_category": null,
                                "children": [],
                                "row_values": [
                                    {
                                        "id": 9897,
                                        "value": "0.91",
                                        "column_id": 171
                                    }
                                ]
                            },
                            {
                                "id": 8452,
                                "name": "Other Income",
                                "line_type": "line",
                                "group_name": "other_income",
                                "financial_category": null,
                                "children": [],
                                "row_values": [
                                    {
                                        "id": 9898,
                                        "value": "459.89",
                                        "column_id": 171
                                    }
                                ]
                            },
                            {
                                "id": 8453,
                                "name": "Sale-Scripps Drive Medical LP 1",
                                "line_type": "line",
                                "group_name": "other_income",
                                "financial_category": null,
                                "children": [],
                                "row_values": [
                                    {
                                        "id": 9899,
                                        "value": "46100.9",
                                        "column_id": 171
                                    }
                                ]
                            }
                        ],
                        "row_values": [
                            {
                                "id": 9810,
                                "value": "46561.7",
                                "column_id": 171
                            }
                        ]
                    }
                  ]
                  }

Borrower

An Borrower is a JSON object that represents an Entity or Individual person. Borrower objects have the following structure:

ssn/ein String String in ###-##-####/##-####### format for Individual and Entity accordingly.
name String Borrower's name
city String Borrower's city
address_1 String Borrower's address_1
address_2 String Borrower's address_2
state String Borrower's state
returns An array of objects. Each object has these fields:
forms Array of Tax Forms (See Data objects section for Form)
schedules Array of Schedules (See Data objects section for Schedule)
Borrower's Tax Returns
financials Array of Unstructrured Document objects. See Data objects section for UnstructruredDocument Borrower's Unstructured Documents
bank_statement_revenue Bank Statement Revenue object. See Data objects section for Bank Statement Revenue Borrower's Bank Statement Revenue

Bank Statement Revenue

A Bank Statement Revenue is a JSON object that represents the summary of borrower bank statement information. Bank Statement Revenue objects have the following structure:

avg_monthly_revenue Decimal Average Monthly Revenue
annual_revenue Decimal Annual Revenue
avg_monthly_true_revenue Decimal Average Monthly True Revenue
annual_true_revenue Decimal Annual True Revenue
avg_monthly_non_true_revenue Decimal Average Monthly Non True Revenue
annual_non_true_revenue Decimal Annual Non True Revenue
avg_monthly_expenses Decimal Average Monthly Expenses
annual_expenses Decimal Annual Expenses
avg_monthly_gross_profit Decimal Average Monthly Gross Profit
annual_gross_profit Decimal Annual Gross Profit
avg_daily_balance Decimal Average Daily Balance
avg_daily_true_balance decimal Average Daily True Balance
combined_days_negative Integer Combined Days Negative
days_negative Integer Days Negative
low_days Integer Low Days
avg_monthly_net_revenue Decimal Average Monthly Net Revenue
annual_net_revenue Decimal Annual Net Revenue
mca_withhold Integer MCA Withhold

Personal Financials Statement

A Personal Financials Statement is a JSON object that represents the summary of personal financials statement information. Personal Financials Statement objects have the following structure:

body Object Container for personal financials fields
description String Description of Other Income in Section 1

Body has the following fields:

assets_cash_on_hand Decimal Cash on Hand & in banks
assets_saving_accounts Decimal Savings Accounts
assets_other_retirement Decimal Ira or other retirement account
assets_accounts_notes Decimal Accounts & notes receivable
assets_life_insurance Decimal Life insurance - cash surrender value only
assets_stocks_and_bonds Decimal Stocks and bonds
assets_real_estate Decimal Real estate
assets_automobiles Decimal Automobiles
assets_other_personal_property Decimal Other personal property
assets_other_assets Decimal Other assets
assets_total Decimal Total
income_salary Decimal Salary
income_net_investment Decimal Net investment income
income_real_estate Decimal Real estate income
income_other Decimal Other income (describe below)
liabilities_accounts_payable Decimal Accounts payable
liabilities_notes_payable Decimal Notes payable to banks and others
liabilities_installment_auto Decimal Installment account (auto)
liabilities_installment_auto_monthly Decimal Mo. payments
liabilities_installment_other Decimal Installment account (other)
liabilities_installment_other_monthly Decimal Mo. payments
liabilities_loans Decimal Loan(s) against life insurance
liabilities_mortgages Decimal Mortgages on real estate
liabilities_unpaid_taxes Decimal Unpaid taxes
liabilities_other_liabilities Decimal Other liabilities
liabilities_total_liabilities Decimal Total liabilities
liabilities_net_worth Decimal Net worth
liabilities_total Decimal Total
liabilities_as_endorser Decimal As endorser or co-maker
liabilities_legal Decimal Legal claims & judgments
liabilities_provision Decimal Provision for federal income tax
liabilities_other_special_debt Decimal Other special debt

Codes

Document Statuses

Status Descriptions
pending The document is queued and waiting on resources for recognition.
processing The document is recognizing
recognized The document was recognized, but still on the Analyzing process
analyzing The document was recognized, but still on the Analyzing process
analyzed The document was analyzed
completed The document was analyzed and successful saved
failed The document was failed in recognizing or analyzing processing
canceled The Recognition process of the document was canceled by the user

Field Statuses

Status Descriptions
invalid_suspicious The field was changes by system and deleted some not recognized symbol, but it is invalid
invalid The field value has some issue
success_suspicious The field was changes, but the value is correct
success The field value has not any issue
not_found The field value was not found on the document

Validation Statuses

Status Descriptions
needs_attention The document hasn't important information (ssn/ein/year)
password_protected The document is password protected
no_support_type The Flashspread didn't found data inside document that we support
no_errors The document doesn't have issues on forms and schedules
please_validate The document has issues on forms or schedules

Review Statuses

Status Descriptions
waiting_for_review The document sent to the DQM, but still preparing data for review
sent_to_review The document sent to the DQM and ready to review
under_review The document is reviewing
review_completed The document was reviewed

Error Handling

Flashspread uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.). Codes in the 5xx range indicate an error with Flashspread's servers (these are rare).

HTTP Status codes

Status Descriptions
200 OK Everything worked as expected.
400 Bad Request The request was unacceptable, often due to missing a required parameter.
401 Unauthorized No valid API key provided
403 Forbidden The API key doesn't have permissions to perform the request.
404 Not Found The requested resource doesn't exist
422 Unprocessable Entity. The problem with validation.
500 Server Errors Something went wrong on Flashspread's end. (These are rare.)
Sample:
                    
                      {
                        "errors": [
                            {
                                "message": "Could not find user in system. Please check your security_key"
                            }
                        ]
                      }

Widget

Flashspread provides a widget that can be dropped into any web page to provide a ready-made UI for users to manage documents.

To add the widget to your application, follow these steps:

  1. Contact an account manager to create a widget token
  2. Add an iframe tag to your web page with the src attribute set to:

https://widget.flashspread.com/upload-center?token={your token}

We recommend also adding these attributes to the iframe:

width 1500
height 805
frameborder 0
style border:0

Query Params

The widget's URL supports several optional query string parameters which filter the records shown:

year One or more four-digit years
ssn One or more SSNs in ###-##-#### format
ein One or more EINs in ##-####### format
dealId One or more deal ids

If multiple values are provided for any of these parameters, they should be comma-delimited.

Example:
                
                  <iframe width="1500"
                          height="805"
                          frameborder="0"
                          style="border:0"
                          src='https://widget.flashspread.com/upload-center?token=some-token&year=2018,2019'>
                  </iframe>

Customization

Widget provides the functionality of UI customization (removing, adding elements and etc).

To customize widget the config json object is required in query parameters:

https://widget.flashspread.com/upload-center?token={your token}&config={config object}'

Available customization options (config object):

                            
                              {
                                "uploadCenter": {
                                  "searchFilter": boolean,
                                  "dropZone": boolean,
                                  "callbackUrl": "https://domain/endpoint"
                                },
                                "tabTitle":"NewTitleName",
                                "userInfo": boolean,
                                "menuTabs": boolean,
                                "showDeals": boolean
                              }

callbackUrl allows you to receive updates about documents, DQM status, and forms. It works as an API hook.

Example:
                            
                              <iframe
                                src='https://widget.flashspread.com/upload-center?token=some-token&config={"userInfo":true, "uploadCenter": {"searchFilter":false}}'>
                              </iframe>

Forms

Widget provides the functionality to access forms.

  1. Access using Navigation:
    1. Via upload center page by clicking on document row.
    2. Via Entity/Individual pages.
  2. Direct access using forms paths.

To have a direct access to forms via widget use the following url for iframe:

https://widget.flashspread.com/forms/{form path}?token={your token}&id={form id}}

Available form paths:

Path Form Type
form-1040 Form 1040
form-1065 Form 1065
form-1120 Form 1120
form-1120s Form 1120s
form-w2 Form W-2
schedule-c Schedule C
schedule-f Schedule F
1120s-schedule-k1 Schedule K1 (Form 1120S)
1065-schedule-k1 Schedule K1 (Form 1065)

Widget V2

Flashspread provides a widget that can be dropped into any web page to provide a ready-made UI for users to manage documents.

To add the widget to your application, follow these steps:

  1. Contact an account manager to create a widget token
  2. Add an iframe tag to your web page with the src attribute set to:

https://widget.flashspread.com/v2/upload-center?token={your token}

We recommend also adding these attributes to the iframe:

width 1500
height 805
frameborder 0
style border:0

Query Params

The widget's URL supports several optional query string parameters which filter the records shown:

year One or more four-digit years
ssn One or more SSNs in ###-##-#### format
ein One or more EINs in ##-####### format
dealId One or more deal ids

If multiple values are provided for any of these parameters, they should be comma-delimited.

Example:
                  
                    <iframe width="1500"
                            height="805"
                            frameborder="0"
                            style="border:0"
                            src='https://widget.flashspread.com/v2/upload-center?token=some-token&year=2018,2019'>
                    </iframe>

Customization

Widget provides the functionality of UI customization (removing, adding elements and etc).

To customize widget the config json object is required in query parameters:

https://widget.flashspread.com/v2/upload-center?token={your token}&config={config object}'

Available customization options (config object):

                    
                      {
                        "uploadCenter": {
                          "searchFilter": boolean,
                          "dropZone": boolean,
                          "callbackUrl": "https://domain/endpoint"
                        },
                        "tabTitle":"NewTitleName",
                        "userInfo": boolean,
                        "menuTabs": boolean,
                        "showDeals": boolean
                      }

callbackUrl allows you to receive updates about documents, DQM status, and forms. It works as an API hook.

Example:
                    
                      <iframe
                        src='https://widget.flashspread.com/v2/upload-center?token=some-token&config={"userInfo":true, "uploadCenter": {"searchFilter":false}}'>
                      </iframe>

Deals

Widget V2 provides the functionality for a deal view. With deal view, users can easily navigate through the deal.

To start using the deal view, the deal identifier and your token are required in parameters:

https://widget.flashspread.com/v2/deals/{deal_identifier}?token={your token}'

Example:
                    
                      <iframe
                        src='https://widget.flashspread.com/v2/deals/{deal_identifier}?token=some-token'>
                      </iframe>

Borrower Info

If a user supplies a borrower flag, and passes in a TIN, the widget provides that borrower’s detail section.

To show specific borrower info, use the following url for iframe::

https://widget.flashspread.com/v2/borrower?token={your_token}&type={borrower_type}&code={tin}

The call should include both of these parameters:

tin Required The borrower's EIN/SSN
type Required Type of borrower. Available types: Entity, Individual
Example:
                  
                    <iframe
                      src='http://localhost:4204/v2/borrower?token=some-token&type=Individual&code=000-00-0000'>
                    </iframe>

Document View

Widget provides the endpoint for the document view.

To show all the forms and schedules attached to the document use the following endponint:

https://widget.flashspread.com/v2/document/:id?token={your token}'

The call should include the document id:

id Required The document's identifier
Example:
                  
                    <iframe
                      src='https://widget.flashspread.com/v2/document/:id?token={your token}'>
                    </iframe>

Report

Widget provides the endpoint for the document view.

To show report use the following endponint:

https://widget.flashspread.com/v2/report/:report_label?code={code}&type={borrower_type}&token={your-token}

The call should include both of these parameters:

report_label Required Internal names of the reports, matching one of the labels returned by List Available Reports.
code Required The borrower's EIN/SSN
type Required Type of borrower. Available types: Entity, Individual
Example:
                  
                    <iframe
                      src='https://widget.flashspread.com/v2/report/default_entity_cashflow?code=00-0000000&type=Entity&token={your-token}'>
                    </iframe>