Download Postman

Introduction Last updated: 2025-12-19

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 Temporary Widget Token Mint a short‑lived widget token (server-side)
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

Headers

  • Content-type: application/json
token String Short-lived widget token

Response

Expected responses:

200 OK {"valid": true} Token is valid
404 Not Found {"valid": false} Token not found or expired
422 Unprocessable Entity Error payload Missing or invalid token parameter

Create Temporary Widget Token

To mint a short‑lived widget token (server-side only), call:

POST /create_temporary_widget_token

Headers

  • Authorization: {Your long‑lived management token}
  • Content-type: application/json

Request Content

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

name String A label to identify the token (for your records)
domain String
Required		 The domain where you embed the widget (e.g., yourapp.example.com)
duration_minutes Integer TTL for the short‑lived token (e.g., 30)

Response

If it succeeds, the content returned will be a JSON object containing the token and expiry under data.attributes:

                
                  {
                    "data": {
                      "id": "123",
                      "type": "widgetToken",
                      "attributes": {
                        "name": "Widget Session - Deal ABC",
                        "domain": "your-embedded-host.com",
                        "value": "eyJhbGciOiJSUzI1NiIs...",
                        "expiresAt": "2025-09-22T15:04:33Z",
                        "createdAt": "2025-09-22T14:34:33Z",
                        "updatedAt": "2025-09-22T14:34:33Z"
                      }
                    }
                  }

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
first_name String Individual's first name
last_name String Individual's last 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 (Legacy Report)

To get Personal Financial Statement legacy report 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 (Legacy Report) object. (See below)

Create or Update Personal Financial Statement (Legacy Report)

To create or update a Personal Financial Statement legacy report, 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 (Legacy Report) 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 (Legacy Report) object. (See below)

PFS Module Overview

The PFS Module uses AI-powered extraction to capture and manage multi-year Personal Financial Statement records for individuals and joint statements with up to two individuals.

Operation Endpoint Description
List Versions GET /personal_financial_statement_document/years Retrieve available PFS years and records for an individual using SSN.
Retrieve Document GET /personal_financial_statement_document Fetch a specific PFS record by personal_financial_statement_document_id, by year, or the latest record.
Update/Mutate Document PUT /personal_financial_statement_document Modify the PFS document, including adding, updating, or deleting line items.

List PFS Versions

To retrieve the available PFS years and records for an individual, call:

GET /personal_financial_statement_document/years

Headers

  • Authorization: {Your access token}

Query Parameters

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

Response

200 OK Response Example:
                
{
  "years": [
    {
      "id": 901,
      "description": "2025 PFS",
      "statement_date": "2025-12-31",
      "year": 2025,
      "document_id": 7821,
      "primary_individual": {
        "id": 2177,
        "name": "Denis Jons",
        "ssn": "123-12-1235"
      },
      "joint_individual": null
    }
  ]
}
Invalid SSN Error Example:
                
{
  "errors": [
    {
      "message": "Resource not found"
    }
  ]
}

Error Codes

401 Unauthorized Missing or invalid access token.
403 Forbidden The API key does not have permission to access PFS documents.
404 Not Found The SSN does not match an accessible individual.

Retrieve PFS Document

To retrieve a PFS Module document, call:

GET /personal_financial_statement_document

Headers

  • Authorization: {Your access token}

Query Parameters

ssn String
Required		 String in ###-##-#### format. The individual's SSN.
personal_financial_statement_document_id Integer Fetches a specific PFS document record.
year Integer Fetches the PFS document for the specified year.
statement_date Not supported statement_date is not currently a lookup parameter.

Lookup precedence is personal_financial_statement_document_id first, then year, then the latest PFS document for the individual when neither is supplied.

Response

If it succeeds, the content returned will be a PFS Document Response object. (See below)

200 OK Response Example:
                
{
  "description": "2025 PFS",
  "statement_date": "2025-12-31",
  "year": 2025,
  "document_id": 7821,
  "individual_names": ["Denis Jons"],
  "ssns": ["123-12-1235"],
  "total_assets": "250000.00",
  "liabilities": "90000.00",
  "net_worth": "160000.00",
  "sections": [
    {
      "key": "assets",
      "title": "Assets",
      "total": "250000.00",
      "line_items": ["pfs-assets-1"]
    }
  ],
  "line_items": [
    {
      "client_id": "pfs-assets-1",
      "description": "Checking account",
      "parent_category": "Assets",
      "section_key": "assets",
      "category": "Cash on hand and in banks",
      "amount": "25000.00",
      "manual": false,
      "flagged": false
    }
  ],
  "validation_summary": {
    "status": "passed_with_warnings",
    "errors_count": 0,
    "warning_count": 1,
    "blocking_count": 0
  },
  "validation_findings": [
    {
      "id": "missing-category-pfs-assets-2",
      "severity": "warning",
      "blocking": false,
      "status": "open",
      "message": "Line item category is recommended."
    }
  ],
  "history_comments": {
    "pfs-assets-1": "Confirmed by reviewer."
  }
}

Error Codes

401 Unauthorized Missing or invalid access token.
403 Forbidden The API key does not have permission to access PFS documents.
404 Not Found The SSN or requested PFS document does not match an accessible record.

Update or Mutate PFS Document

To update a PFS Module document, call:

PUT /personal_financial_statement_document

Headers

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

Request Content

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

ssn String
Required		 String in ###-##-#### format. The individual's SSN.
personal_financial_statement_document_id Integer Updates a specific PFS document. Required when year is not used for create/upsert.
year Integer Creates or updates the PFS document for the specified year when no document ID is supplied.
statement_date Date Accepted as document metadata. It is not a lookup parameter.
sections Array Structured PFS sections. Valid top-level section titles are Assets, Liabilities, Income, Expenses, and Contingent Liabilities.
line_items Array Structured line items to add, update, or delete. Use destroy: true to delete a line item.
validation_summary Object Summary of automated extraction errors and warnings.
validation_findings Array Automated extraction errors and warnings for review.
history_comments Object Audit comments keyed by field or line item identifier.
validation_decisions Array Reviewer decisions for validation findings.

Nested Schemas

Structured arrays may contain at most 500 objects. Unknown object keys are rejected.

sections

Each section object defines a top-level PFS section and the line item identifiers assigned to it.

key String
Required		 Canonical section key. Supported values: assets, liabilities, income, expenses, contingent_liabilities.
title String Human-readable section title. Supported values: Assets, Liabilities, Income, Expenses, Contingent Liabilities.
total Decimal Section total as a number or numeric string.
line_items Array Line item client IDs associated with the section.
history_comment String Audit comment for the section-level change.
line_items

Each line item object represents an extracted or manual PFS value. category and amount are recommended, but missing values currently create non-blocking validation warnings.

id String or Integer Existing source or external identifier when available.
client_id String Stable client-side identifier used by sections.line_items, history comments, and validation finding locations.
description String Line item label or description.
parent_category String Human-readable parent section title.
section_key String
Required		 Canonical section key matching a sections.key value.
category String Financial category label. Recommended for downstream calculations.
category_selection String Reviewer-selected category value when different from the extracted category.
financial_category_id / financialCategoryId Integer Backend financial category identifier.
amount Decimal Line item amount as a number or numeric string. Recommended for downstream calculations.
extracted Boolean Whether the line item came from automated extraction.
manual Boolean Whether the line item was manually added.
flagged Boolean Whether the line item should be flagged for review.
history_comment String Audit comment for the line item change.
source_field_key String Source extraction field key used to map validations back to OCR data.
errors Array Scalar error labels associated with the line item.
destroy Boolean Set destroy: true to delete the line item. Include client_id or id plus section_key so the deleted item remains traceable.
included_downstream Boolean Set false to exclude the line item from downstream calculations.
confidence / confidence_score / confidenceScore Decimal Extraction confidence score.
confidence_tier / confidenceTier String Extraction confidence tier.
confidence_source / confidenceSource String Source of the confidence value.
validation_findings / validationFindings Array Line-item validation finding objects using the validation_findings shape in the PFS Document Response.
validation_decisions

Each validation decision records a reviewer decision for a validation finding.

finding_id / findingId String
Required		 Identifier of the validation finding being reviewed.
decision_type / decisionType String
Required		 Supported values: ACCEPT_AS_IS, FIXED_VALUE, REQUESTED_NEW_DOC, HIDE_FINDING, REOPEN_FINDING.
source_decision_id / sourceDecisionId String
Required		 Partner-provided idempotency key for the decision.
corrected_value / correctedValue String, Number, Boolean, Array, or Object Corrected value supplied with FIXED_VALUE decisions.
comments String Reviewer comments for the decision.
decided_at / decidedAt DateTime Timestamp supplied by the caller when available.
metadata Object Additional decision metadata.
Request Example:
                
{
  "ssn": "123-12-1235",
  "personal_financial_statement_document_id": 901,
  "year": 2025,
  "statement_date": "2025-12-31",
  "sections": [
    {
      "key": "assets",
      "title": "Assets",
      "total": "250000.00",
      "line_items": ["pfs-assets-1", "manual-assets-1"]
    }
  ],
  "line_items": [
    {
      "client_id": "manual-assets-1",
      "description": "Brokerage account",
      "parent_category": "Assets",
      "section_key": "assets",
      "category": "Stocks and bonds",
      "amount": "55000.00",
      "manual": true,
      "history_comment": "Added from reviewer notes."
    },
    {
      "client_id": "pfs-assets-1",
      "description": "Checking account",
      "parent_category": "Assets",
      "section_key": "assets",
      "category": "Cash on hand and in banks",
      "amount": "25000.00"
    },
    {
      "client_id": "pfs-assets-removed",
      "section_key": "assets",
      "destroy": true,
      "history_comment": "Duplicate item removed."
    }
  ],
  "history_comments": {
    "manual-assets-1": "Added from reviewer notes.",
    "pfs-assets-removed": "Duplicate item removed."
  },
  "validation_decisions": [
    {
      "finding_id": "missing-category-pfs-assets-2",
      "decision_type": "ACCEPT_AS_IS",
      "source_decision_id": "partner-review-001",
      "comments": "Reviewer accepted the warning."
    }
  ]
}

Response

If it succeeds, the content returned will be the updated PFS Document Response object. (See below)

200 OK Response Example:
                
{
  "description": "2025 PFS",
  "statement_date": "2025-12-31",
  "year": 2025,
  "document_id": 7821,
  "sections": [
    {
      "key": "assets",
      "title": "Assets",
      "total": "250000.00",
      "line_items": ["pfs-assets-1", "manual-assets-1"]
    }
  ],
  "line_items": [
    {
      "client_id": "pfs-assets-1",
      "description": "Checking account",
      "parent_category": "Assets",
      "section_key": "assets",
      "category": "Cash on hand and in banks",
      "amount": "25000.00"
    },
    {
      "client_id": "manual-assets-1",
      "description": "Brokerage account",
      "parent_category": "Assets",
      "section_key": "assets",
      "category": "Stocks and bonds",
      "amount": "55000.00",
      "manual": true
    }
  ],
  "validation_summary": {
    "status": "passed_with_warnings",
    "errors_count": 0,
    "warning_count": 1,
    "blocking_count": 0
  },
  "validation_findings": [
    {
      "id": "missing-category-pfs-assets-2",
      "severity": "warning",
      "blocking": false,
      "status": "accepted",
      "message": "Line item category is recommended."
    }
  ],
  "history_comments": {
    "manual-assets-1": "Added from reviewer notes.",
    "pfs-assets-removed": "Duplicate item removed."
  }
}

Error Codes

401 Unauthorized Missing or invalid access token.
403 Forbidden The API key does not have permission to update PFS documents.
404 Not Found The SSN or requested PFS document does not match an accessible record.
422 Unprocessable Entity The request body failed validation.

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

Get Unstructured Documents

To get unstructured documents for each uploaded document, call:

GET /unstructured_documents/:document_id

Headers

  • Authorization: {Your access token}

Query Parameters

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

document_id String
Required		 A uploaded document that Flashspread uses to create unstructured documents

Request Content

The request content should be empty.

Response

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

Example:
 [  ]

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
  • X-Signature: lowercase hex-encoded HMAC-SHA256 digest of string_to_sign (see Request Headers below)
  • X-Timestamp: UTC ISO 8601, same value as the first segment of string_to_sign
  • X-Nonce: unique per request, same value as the second segment of string_to_sign
  • X-Source (optional): not included in the signature input

Request Headers

X-Signature String
Required
  • Generated with HMAC-SHA256 only.
  • Output format: lowercase hex-encoded digest.
  • Secret key: shared secret used by both sender and receiver to compute and verify X-Signature.
Validate:
  • X-Timestamp and X-Nonce are present.
  • X-Timestamp is within the allowed time window (for example, 5 minutes).
  • X-Nonce has not been used before.
Recompute the signature:
  • For GET requests: string_to_sign = "{X-Timestamp}.{X-Nonce}.{raw_query_string}"
  • For POST/PUT/PATCH requests: the third segment is the raw request body exactly as received. Do not parse the JSON and re-serialize it, do not normalize whitespace, do not reorder fields, and do not trim the body. string_to_sign = "{X-Timestamp}.{X-Nonce}.{raw_body}" where raw_body is the exact request body string used on the wire. If your framework parses JSON automatically, capture the raw body before parsing; otherwise verification can fail even when the JSON data is logically the same.
  • signature = HMAC_SHA256(secret, string_to_sign)
Compare: signature to X-Signature using constant-time comparison.
X-Timestamp String
Required		 Request creation time in UTC ISO 8601 format. This exact value is the first segment in string_to_sign.
X-Nonce String
Required		 Unique random value per request (for example, UUID). This exact value is the second segment in string_to_sign and must be rejected if replayed.
X-Source String
Optional		 Identifies the origin system of the webhook request. This header is metadata and is not part of the signature input.

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
unstructured_documents[] Object Unstructured documents object. (see below)

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:

Webhooks may be delivered with POST/PUT/PATCH (JSON body) or GET (query string). For POST/PUT/PATCH, the third segment of string_to_sign is the raw request body: the body exactly as received, before any JSON parsing or formatting changes. Preserve whitespace, field order, escaping, and trailing newlines exactly; do not pretty-print, compact, trim, or otherwise normalize the JSON. For GET, the third segment is the raw query string: the substring of the request URI after ?, excluding ? itself, exactly as received (including percent-encoding and parameter order).

POST
Headers
                  
                    Content-Type: application/json
                    X-Signature: d271f8aad23f7b443c6916446d3e09ddb8a24a243295bbec508ff4c923f9ff3d
                    X-Timestamp: 2026-04-10T10:10:42.968Z
                    X-Nonce: 456783ff-f7ad-4999-9220-591664f0bab1
Content (raw body - third segment; exactly as received)
                  {"status":"processing","event":"processing_status_changed","validation_status":null,"review_status":null,"document_id":"263"}
String to sign (POST)
                  2026-04-10T10:10:42.968Z.456783ff-f7ad-4999-9220-591664f0bab1.{"status":"processing","event":"processing_status_changed","validation_status":null,"review_status":null,"document_id":"263"}

X-Signature = HMAC_SHA256(shared_secret, string_to_sign) as lowercase hex. The digest above is illustrative; recompute with your shared secret to verify.

GET
Request
                  GET https://your-endpoint.example/your-webhook-path?document_id=263&event=processing_status_changed
Headers
                  
                    X-Signature: 8e4c2b1a9f0d3e7c6b5a4938271605f4c3d2e1a0987654321fedcba987654321
                    X-Timestamp: 2026-04-10T10:15:00.000Z
                    X-Nonce: 9c0e1f2a-3b4c-5d6e-7f80-91a2b3c4d5e6
String to sign (GET)

Third segment = raw query string only (here: document_id=263&event=processing_status_changed).

                  2026-04-10T10:15:00.000Z.9c0e1f2a-3b4c-5d6e-7f80-91a2b3c4d5e6.document_id=263&event=processing_status_changed

X-Signature = HMAC_SHA256(shared_secret, string_to_sign) as lowercase hex. The digest above is illustrative; recompute with your shared secret to verify.

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 five types of Form object. All of them have these fields in common:

type String The form's type, one of:
  • Forms::Form1120
  • Forms::Form1120S
  • Forms::Form1120H
  • Forms::Form1065
  • Forms::Form990
  • 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
schedule_m3 Schedule object 1120S Schedule M3

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
schedule_m3 Schedule object 1120 Schedule M3

Form 1120H object

entity Entity object Form's Entity

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
schedule_m3 Schedule object 1065 Schedule M3

Form 990 object

entity Entity object Form's Entity

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_m3 1120S Schedules::Form1120S::ScheduleM3
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_m3 1120 Schedules::Form1120::ScheduleM3
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
schedule_m3 1065 Schedules::Form1065::ScheduleM3
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
first_name String Individual's first name
last_name String Individual's last 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 (Legacy Report)

A Personal Financials Statement legacy report is a JSON object that represents the summary of manually entered personal financial statement information. Personal Financials Statement legacy report 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

PFS Document Response

A PFS Document Response is the primary response object for the PFS Module. It includes extracted data, structured sections and line items, validation results, and history comments.

body Object Raw structured document body.
description String Document description.
statement_date Date Statement date associated with the PFS document.
year Integer PFS document year.
document_id Integer Source document identifier when available.
individual_names Array Names extracted for the individual or joint individual.
ssns Array SSNs extracted from the document.
total_assets Decimal Total assets value.
liabilities Decimal Total liabilities value.
net_worth Decimal Net worth value.
sections Array Structured PFS sections, including section key, title, total, and line item references.
line_items Array Structured extracted and manual line items.
history_comments Object Audit comments keyed by field or line item identifier.
document_url String Document URL when available.
pdf_url String PDF URL when available.
metadata Object Additional document metadata.
validation_findings Array Automated extraction errors and warnings.
validation_summary Object Summary counts and status for validation findings.
errors_count Integer Total error count.
blocking_validation_findings Array Validation findings that block downstream processing.

validation_summary

validation_summary is an object used to review automated extraction validation at a glance. Common fields include status, errors_count, warning_count, informational_count, blocking_count, and effective_confidence_threshold.

validation_findings

validation_findings is an array of validation finding objects. Each finding can include id, rule_id, severity, blocking, message, status, source, location, recommended_action, expected, actual, confidence, and document_refs.

history_comments

history_comments is an object containing audit comments for manual and system changes. Values are scalar comments keyed by the related field or line item identifier.

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
pending_processing The document has not been sent to or completed OCR processing yet

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 your Flashspread account manager to obtain a long‑lived token (LLT) and enable widget access for your tenant.
  2. From your server, mint a short‑lived widget token (SLT) using your long‑lived token (LLT). Do not expose the LLT to the client.
  3. Add an iframe tag to your web page with the src attribute set to:

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

We recommend also adding these attributes to the iframe. Because widget tokens are short‑lived, refresh by obtaining a new token on your server and updating the iframe src before expiry.

Authentication with Short‑Lived Tokens

  • Mint widget tokens on your server using your long‑lived token (LLT). Never expose the LLT to browsers or mobile apps.
  • Tokens are short‑lived (e.g., 5–15 minutes). Refresh proactively ~80–90% into the TTL and allow 30–60s clock skew.
  • On expiry (or HTTP 401/403), obtain a fresh token from your server and reload the iframe src with the new token.
  • Optionally validate tokens with POST /validate_widget_token.
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>

Token refresh via window.postMessage

This section shows a practical pattern to refresh the short‑lived widget token without full page reloads, using window.postMessage from the widget to the parent and vice‑versa. You can choose the exact message types your app listens for, as long as both sides agree on the same schema.

Parent listens for token requests (reactive)

When the widget detects the token is invalid/expired, it can notify the host page. The parent receives the message, fetches a fresh token from your backend, then posts the new token back to the widget.

                            
// Parent page (host) example
// 1) Add an id to your iframe so you can target it
//    <iframe id="fs-widget" src="https://widget.flashspread.com/upload-center?token=INITIAL_TOKEN"></iframe>

// 2) Listen for token requests from the widget
window.addEventListener('message', async (event) => {
  if (event.origin !== 'https://widget.flashspread.com') return;

  const data = event.data || {};
  if (data.type === 'FS_WIDGET_TOKEN_PREEXPIRY' || data.type === 'FS_WIDGET_TOKEN_EXPIRED') {
    try {
      // Ask your backend to mint a fresh short‑lived token
      const resp = await fetch('/api/flashspread/token', { method: 'POST', credentials: 'include' });
      const { token, expires_at } = await resp.json();

      // Send the new token to the widget
      const iframe = document.getElementById('fs-widget');
      iframe.contentWindow.postMessage(
        { type: 'FS_WIDGET_TOKEN_UPDATE', token, expires_at },
        'https://widget.flashspread.com'
      );
    } catch (e) {
      console.error('Failed to refresh Flashspread token', e);
    }
  }
});

Parent proactively refreshes before expiry

Optionally decode the token’s expiration and refresh ~80–90% into the TTL. This reduces the chance of mid‑flow 401/403s.

                            
// Parent page (host) example
function scheduleProactiveRefresh(expiresAtEpochSeconds) {
  // Refresh ~90% into TTL and allow ~45s skew
  const now = Math.floor(Date.now() / 1000);
  const secondsUntilExpiry = Math.max(0, expiresAtEpochSeconds - now - 45);
  const refreshDelayMs = Math.floor(secondsUntilExpiry * 0.9) * 1000;

  window.setTimeout(async () => {
    try {
      const resp = await fetch('/api/flashspread/token', { method: 'POST', credentials: 'include' });
      const { token, expires_at } = await resp.json();

      const iframe = document.getElementById('fs-widget');
      iframe.contentWindow.postMessage(
        { type: 'FS_WIDGET_TOKEN_UPDATE', token, expires_at },
        'https://widget.flashspread.com'
      );

      // Re-schedule the next refresh
      scheduleProactiveRefresh(expires_at);
    } catch (e) {
      console.error('Proactive Flashspread token refresh failed', e);
    }
  }, Math.max(5_000, refreshDelayMs)); // minimum 5s delay
}

Fallback: reload the iframe src with a fresh token

If your integration can’t apply a live update, reload the iframe src with the new token parameter.

                            
async function hardReloadWidget() {
  const resp = await fetch('/api/flashspread/token', { method: 'POST', credentials: 'include' });
  const { token } = await resp.json();

  const iframe = document.getElementById('fs-widget');
  const url = new URL(iframe.src);
  url.searchParams.set('token', token);
  iframe.src = url.toString(); // navigates the widget with a fresh token
}

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 short-lived 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 short-lived 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-1120h Form 1120H
form-990 Form 990
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 your Flashspread account manager to obtain a long‑lived token (LLT) and enable widget access for your tenant.
  2. From your server, mint a short‑lived widget token (SLT) using your long‑lived token (LLT). Do not expose the LLT to the client.
  3. Add an iframe tag to your web page with the src attribute set to:

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

We recommend also adding these attributes to the iframe. Because widget tokens are short‑lived, refresh by obtaining a new token on your server and updating the iframe src before expiry.

Authentication with Short‑Lived Tokens

  • Mint widget tokens on your server using your long‑lived token (LLT). Never expose the LLT to browsers or mobile apps.
  • Tokens are short‑lived (e.g., 5–15 minutes). Refresh proactively ~80–90% into the TTL and allow 30–60s clock skew.
  • On expiry (or HTTP 401/403), obtain a fresh token from your server and reload the iframe src with the new token.
  • Optionally validate tokens with POST /validate_widget_token.
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>

Token refresh via window.postMessage

Widget V2 supports the same parent/child messaging approach for refreshing short‑lived tokens. The parent hosts the iframe and coordinates token refresh; the widget runs at https://widget.flashspread.com.

Parent listens for token requests (reactive)

                    
// Parent page (host) example for Widget V2
// Add an id to your iframe:
// <iframe id="fs-widget-v2" src="https://widget.flashspread.com/v2/upload-center?token=INITIAL_TOKEN"></iframe>

window.addEventListener('message', async (event) => {
  if (event.origin !== 'https://widget.flashspread.com') return;

  const data = event.data || {};
  if (data.type === 'FS_WIDGET_TOKEN_PREEXPIRY' || data.type === 'FS_WIDGET_TOKEN_EXPIRED') {
    try {
      const resp = await fetch('/api/flashspread/token', { method: 'POST', credentials: 'include' });
      const { token, expires_at } = await resp.json();

      const iframe = document.getElementById('fs-widget-v2');
      iframe.contentWindow.postMessage(
        { type: 'FS_WIDGET_TOKEN_UPDATE', token, expires_at },
        'https://widget.flashspread.com'
      );
    } catch (e) {
      console.error('Failed to refresh Flashspread token', e);
    }
  }
});

Proactive refresh and fallback

As with Widget, schedule a proactive refresh using the token’s expiry, and if needed, reload the iframe src with an updated token:

                    
function reloadV2Iframe(token) {
  const iframe = document.getElementById('fs-widget-v2');
  const url = new URL(iframe.src);
  url.searchParams.set('token', token);
  iframe.src = url.toString();
}

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 short-lived 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 short-lived token are required in parameters:

https://widget.flashspread.com/v2/deals/{deal_identifier}?token={your short-lived 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 short-lived 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 short-lived 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 short-lived 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>