Introduction

Welcome to the documentation for BlueSuit's ExtractAPI! BlueSuit extracts data from documents and returns them back to you via our API. You can view code examples that use curl to the right.

You Should Know

Our API is asynchronous.

Our API is rate limited.

Your API key must be included in all API requests sent to the server.

Get Started

Get your API key from your BlueSuit dashboard.
Submit your document to its specific document endpoint. For example - you will send your Rent Roll document to a specific Rent Roll endpoint.
When you send a document, you will be given a requestId (a UUIDv4) to reference.
Due to our asynchronous process, the response will take a few minutes before it's ready. While you are waiting, you will be able to check on the status of our extraction process while it is in process.
Once your data is ready, the status endpoint will return a redirect to the response endpoint when you check it, & you will be able to grab the response data.
You will be able to track your usage on your BlueSuit dashboard.

Authentication

BlueSuit uses API keys to allow access to our API, and to send and receive information. You will get an API key in your BlueSuit dashboard, in the Developers section.

BlueSuit requires your API key to be included in all API requests sent to the server, in an x-api-key header that looks like this:

"x-api-key: PutYourSpecialAPIKeyHereIfYouWantThisToWork"

Replace PutYourSpecialAPIKeyHereIfYouWantThisToWork with your personal API key.

Rate Limiting

User-to-server requests are rate limited at 100 requests per second and per API key, with a limit of 1,000 open requests per API key allowed at any time.

A total of 10,000 requests per API key are allowed per calendar month. To increase this limit, please contact us.

Send Document

This type of endpoint sends a document to BlueSuit for a specific sort of processing. We have unique endpoints for each document type we process, and unique endpoints for each processing type you can request.

These endpoints accept HTTP POST requests containing document data in binary format. Content-Type and x-api-key headers must be present on your request.

Once your document has been submitted, these endpoints will return an HTTP 202 response containing a requestId you can use to check the status of your request. A link to the status endpoint will also be provided in the Location header of the HTTP 202.

The only Content-Type type currently accepted is application/pdf.

Endpoints

You will send your document to an endpoint for processing. There are several route options for the type of processing you need, and the type of document you are sending.

HTTP Request

POST https://extract.bluesuit.com/v1/document_type/processing_type

curl -X POST
  -H "Content-Type: application/pdf"
  -H "x-api-key: PutYourSpecialAPIKeyHereIfYouWantThisToWork"
  --data-binary "@/your/file/location/filename.pdf" "https://extract.bluesuit.com/v1/document_type/processing_type"

You need to add both a document_type route and a processing_type route to your HTTP request.

Complete list of Endpoints

This is the complete list of current endpoints. Depending on the processing_type route you choose, response time may vary significantly.

Endpoint	Description
`rent_roll/accurate`	Rent Roll documents, processing time may be extended to ensure accuracy
`rent_roll/quick`	Rent Roll documents
`closing_disclosure/quick`	Closing Disclosure documents
`property_deed/quick`	Property Deed documents
`psa/foundational/quick`	Purchase and Sale Agreement documents (data returned as entities)

Processing Routes

Documents can be processed two ways - with a guarantee of accuracy, or with a focus on speed. There are different costs associated with each processing type.

Route	Description
`accurate`	(Currently only available for Rent Roll documents.) Data returned will have an accuracy guarantee; processing time may be longer.
`quick`	Data is returned with a focus on speed with an accuracy score of `pass` or `fail`.

Document Routes

You will send your document to the route that corrollates with what sort of document it is.

Route	Description
`closing_disclosure`	Closing Disclosure documents
`property_deed`	Property Deed documents
`rent_roll`	Rent Roll documents
`psa/foundational`	Purchase and Sale Agreement documents (data returned as entities)

Check Status

Once your document is submitted, you will use your requestId to check on your status and get your results.

This is accomplished by hitting the status endpoint with your requestId passed as a query string parameter.

While your document is pending, this endpoint will return an HTTP 202 confirming that the document has been accepted for processing. Once your document has finished processing, this endpoint will return an HTTP 302 that redirects to the response endpoint via the Location header.

HTTP Request

curl -H "x-api-key: PutYourSpecialAPIKeyHereIfYouWantThisToWork"
  "https://extract.bluesuit.com/v1/status?requestId=your-requestId-here"

GET https://extract.bluesuit.com/v1/status?requestId=your-requestId-here

The command will return this message while your document is processing:

{ "message": "Accepted", "requestId": "your-requestId-here" }

Once your document has finished processing, you will see this message when you check the status:

{ "message": "Found", "requestId": "your-requestId-here" }

HTTP Status Codes

Status Code	Description	Meaning
202	Accepted	Your document is being processed.
302	Found	The response is ready.
400	Error	Bad Request
404	Error	Not Found
422	Error	There was an extraction error.
429	Warning	Too many requests
500	Error	Internal Server Error

Retrieve Response

Once your document has finished processing, you will use your requestId to retrieve the response.

The JSON structure of the response payload will vary based on the endpoint the document was initially submitted to.

HTTP Request

GET https://extract.bluesuit.com/v1/response?requestId=your-requestId-here

curl -H "x-api-key: PutYourSpecialAPIKeyHereIfYouWantThisToWork"
  "https://extract.bluesuit.com/v1/response?requestId=your-requestId-here"

Responses

AccuracyIQ

AccuracyIQ is returned as either pass or fail.

View or hide the expected JSON response

{ "accuracyiq": 'pass', }

Closing Disclosure

Closing disclosure data groups are returned as a JSON object. You will see an overview section with select pieces data, as well as raw data section that contains the full, unfiltered data extraction.

Overview Data: View or hide the expected JSON response

{ "overview":
"date_issued": "12-14-2020", "closing_date": "12-15-2020", "disbursement_date": "12-15-2020", "settlement_agent": "Josh Allen LLC" "file_num": "503784-32473", "property_street_address": "1 Bills Drive" "property_city": "Orchard Park" "property_state": "New York" "property_zipcode": "14127" "property_value": 100000000, "borrower_name": "D'artagnan Trimarche" "borrower_street_address": "43-16 Main Street STE 1452" "borrower_city": "Buffalo" "borrower_state": "New York" "borrower_zipcode": "14222" "lender_name": "K & T Reguli LLC NFM" "lender_street_address": "", "lender_city": "", "lender_state": "", "lender_zipcode": "", "loan_term": 24, "purpose": "Refinance", "product": "", "loan_type": "conventional", "loan_id": "7-7-7-7" "mic_num": text "loan_amount": 90000000, "interest_rate": 2.97, "monthly_principal_and_interest": 1234, "closing_costs": 600000, "cash_to_close": 1000000, }

Raw Data: View or hide the expected JSON response

{ "message": "OK", "requestId": "your-requestId-here", "response": { "loan_costs": { "total_loan_costs": { "items": [ { "item": "Loan Costs Subtotals (A + B + C)", "borrower_paid": { "at_closing": 1000.00, "before_closing": 1000.00 } } ], "borrower_paid": 1000.00 }, "origination_charges": { "items": [ { "item": "% of Loan Amount (Points)" }, { "item": "Application Fee to BlueSuit Bank", "borrower_paid": { "before_closing": 1000.00 } }, { "item": "Loan Origination Fee to BlueSuit Bank", "borrower_paid": { "at_closing": 1000.00 } } ], "borrower_paid": 1000.00 }, "services_borrower_did_shop_for": { "items": [ { "item": "See Additional C.01 Items", "paid_by_others": 1000.00 }, { "item": "Title - E-Recording Fee to BlueSuit Title", "borrower_paid": { "at_closing": 1000.00 } }, ], "borrower_paid": 1000.00 }, "services_borrower_did_not_shop_for": { "items": [ { "item": "Credit Report Fee to BlueSuit Data", "paid_by_others": 1000.00 }, ], "borrower_paid": 1000.00 } }, "loan_terms": { "loan_amount": { "value": 1000.00, "amount_can_increase": "NO" }, "interest_rate": { "value": 2.5, "amount_can_increase": "NO" }, "balloon_payment": { "loan_has_feature": "NO" }, "prepayment_penalty": { "loan_has_feature": "NO" }, "monthly_principal_and_interest": { "value": 1000.00, "amount_can_increase": "NO" } }, "other_costs": { "other": { "items": [], "borrower_paid": 1000.00 }, "prepaids": { "items": [ { "item": "Mortgage Insurance Premium ( mo.)" }, { "item": "Prepaid Interest ($1000.00 per day from 01/01/2021 to 12/31/2021)", "borrower_paid": { "at_closing": 1000.00 } }, ], "borrower_paid": 1000.00 }, "total_other_costs": { "items": [ { "item": "Other Costs Subtotals (E + F + G + H)", "borrower_paid": { "at_closing": 1000.00 } } ], "borrower_paid": 1000.00 }, "total_closing_costs": { "items": [ { "item": "Closing Costs Subtotals (D + I)", "borrower_paid": { "at_closing": 1000.00, "before_closing": 1000.00 }, "paid_by_others": 1000.00 }, { "item": "Lender Credits" } ], "borrower_paid": 1000.00 }, "taxes_and_other_government_fees": { "items": [ { "item": "Recording Fees Deed: Mortgage: $1000.00", "borrower_paid": { "at_closing": 1000.00 } } ], "borrower_paid": 1000.00 }, "initial_escrow_payment_at_closing": { "items": [ { "item": "Homeowner's Insurance $1000.00 per month for 12 mo.", "borrower_paid": { "at_closing": 1000.00 } }, { "item": "Mortgage Insurance" }, { "item": "Property Taxes See additional G.03 items", "borrower_paid": { "at_closing": 1000.00 } }, { "item": "Aggregate Adjustment" } ], "borrower_paid": 1000.00 } }, "costs_at_closing": { "cash_to_close": { "value": 1000.00, "includes_closing_costs": { "to_borrower": false, "from_borrower": true } }, "closing_costs": { "total": 1000.00, "sub_costs": [ { "item": "Loan Costs", "value": 1000.00 }, { "item": "Other Costs", "value": 1000.00 } ] } }, "loan_disclosures": { "assumption": [ { "item": "If you sell or transfer this property to another person, your lender will allow, under certain conditions, this person to assume this loan on the original terms.", "value": false }, { "item": "If you sell or transfer this property to another person, your lender will not allow assumption of this loan on the original terms.", "value": true } ], "late_payment": { "late_fee": "", "days_late": "" }, "escrow_account": { "details": { "table": { "initial_escrow_payment": 1000.00, "monthly_escrow_payment": 1000.00, "escrowed_property_costs_over_year_1": 1000.00, "non_escrowed_property_costs_over_year_1": 1000.00 }, "reason_no_escrow": "" }, "escrow_exists": true }, "demand_features": [ { "item": "Your loan has a demand feature, which permits your lender to require early repayment of the loan. You should review your note for details.", "value": false }, { "item": "Your loan does not have a demand feature.", "value": true } ], "partial_payments": [ { "item": "Your lender may accept payments that are less than the full amount due (partial payments) and apply them to your loan.", "value": false }, { "item": "Your lender may hold them in a separate account until you pay the rest of the payment, and then apply the full payment to your loan.", "value": false }, { "item": "Your lender does not accept any partial payments.", "value": false } ], "negative_amortization": [ { "item": "Under your loan terms, you are scheduled to make monthly payments that do not pay all of the interest due that month. As a result, your loan amount will increase (negatively amortize), and, your loan amount will likely become larger than your original loan amount. Increases in your amount lower the equity you have in this property.", "value": false }, { "item": "Under your loan terms, you may have monthly payments that do not pay all of the interest due that month. If you do, your loan amount will increase (negatively amortize), and, as a result, your loan amount may become larger than your original loan amount. Increases in your loan amount lower the equity you have in this property.", "value": false }, { "item": "Under your loan terms, you do not have a negative amortization feature.", "value": true } ] }, "loan_information": { "mic_num": "", "product": "", "purpose": "Refinance", "loan_term": 1000.00, "loan_type": { "va": false, "fha": false, "other": false, "other_type": "", "conventional": true }, "loan_id_num": "8675309" }, "loan_calculations": { "finance_charge": 0, "amount_financed": 0, "total_of_payments": 0, "annual_percentage_rage": 0, "total_interest_percentage": 0 }, "other_disclosures": { "liability_after_forclosure": { "state_law_protection": false, "state_law_no_protection": true } }, "projected_payments": { "payment_calculation": { "estimated_escrow": 1000.00, "mortgage_insurance": 0, "principal_and_interest": 1000.00, "estimated_total_monthly_payment": 1000.00 }, "estimated_taxes_insurance_and_assessments": { "value": 1000.00, "estimate_includes": { "property_taxes": { "included": true, "in_escrow": "YES" }, "homeowners_insurance": { "included": true, "in_escrow": "YES" } } } }, "closing_information": { "file_num": "8675309", "property": "1644 Platte St\nDenver, CO 80202", "date_issued": "01/01/2021", "closing_date": "01/01/2021", "settlement_agent": "BlueSuit Title", "disbursement_date": "01/01/2021", "estimated_prop_value": 1000.00 }, "contact_information": { "lender": { "name": "BlueSuit Bank", "email": "hello@bluesuit.com", "phone": "", "address": "1644 Platte St\nDenver, CO 80202", "contact": "Jeff Harrison", "nmls_id": "", "in_license_id": "000000", "contact_nmls_id": "", "contact_in_license_id": "000000" }, "mortgage_broker": { "name": "", "email": "", "phone": "", "address": "", "contact": "", "nmls_id": "", "in_license_id": "", "contact_nmls_id": "", "contact_in_license_id": "" }, "settlement_agent": { "name": "BlueSuit Title", "email": "", "phone": "", "address": "1644 Platte St\nDenver, CO 80202", "contact": "", "nmls_id": "", "in_license_id": "000000", "contact_nmls_id": "", "contact_in_license_id": "000000" } }, "payoffs_and_payments": { "items": [ { "to": "Payoff First Mortgage to BlueSuit Bank", "amount": 1000.00 } ], "total_payoffs_and_payments": 1000.00 }, "transaction_information": { "lender": "BlueSuit Bank", "borrower": "Jeff Harrison\n123 Fake Dr\nDenver, CO 80202" }, "calculating_cash_to_close": { "items": [ { "item": "Loan Amount", "final": 1000.00, "changed": "YES", "loan_estimate": 1000.00 }, { "item": "Total Closing Costs (J)", "final": -1000.00, "changed": "YES", "loan_estimate": 1000.00 }, { "item": "Closing Costs Paid Before Closing", "final": 1000.00, "changed": "YES", "loan_estimate": 1000.00 }, { "item": "Total Payoffs and Payments (K)", "final": -1000.00, "changed": "YES", "loan_estimate": 1000.00 } ], "cash_to_close": { "final": { "value": 1000.00, "to_borrower": false, "from_borrower": true }, "changed": "Closing Costs Financed (Paid from your Loan Amount) $1000.00", "loan_estimate": { "value": 1000.00, "to_borrower": false, "from_borrower": true } } }, "closing_disclosure_attachment": { "lender": "BlueSuit Bank", "payoffs": [ { "payee": "The BANK", "description": "Payoff First Mortgage", "loan_payoff": 1000.00, "total_payoff": 1000.00, "paid_by_others": 0, "additional_interest": { "interest": -1000.00, "per_diem": 1000.00, "from_date": "01/01/2021", "through_date": "12/31/2021" }, "borrower_paid_at_closing": 1000.00, "borrower_paid_before_closing": 0 } ], "borrower": "Jeff Harrison\n123 Fake Dr\nDenver, CO 80202", "closing_date": "January 1, 2021", "settlement_agent": "BlueSuit Title\n4 Fake Street\nDenver, CO 80202\n(555)555-5555", "disbursement_date": "January 1, 2021", "property_location": "123 Fake Dr\nDenver, CO 80202" } }, "errorMessage": null }

Property Deed

Property Deed data groups are returned as a JSON object.

View or hide the expected JSON response

{ "message": "OK", "requestId": "your-requestId-here", "response": { "bp": ["2412", "1504"], "instrument": "101070856", "executed_date":"2017-06-05", "recorded_date": "2017-06-05", "grantor": "Breaux Alexander Murphy", "grantee": "Breaux Alexander Murphy, Trustee of the Breaux Alexander Murphy Trust dated June 5, 2017", "consideration": 10, "legal_description": "UNIT 1B, BUILDING II, SILVER TOWN CONDOMINIUMS, A UTAH\nCONDOMINIUM PROJECT, TOGETHER WITH ITS APPURTENANT\nUNDIVIDED OWNERSHIP INTEREST IN THE COMMON AREAS TO THE\nABOVE MENTIONED UNIT OF SAID SILVER TOWN CONDOMINIUUMS,\nWHICH INTEREST IS ESTABLISHED AND IDENTIFIED IN THE\nCONDOMINIUM DECLARATION, RECORDED AS ENTRY NO. 137917\nAND SURVEY MAP FILED FOR RECORD AS ENTRY NO. 13267 AND AS\nMAY BE AMENDED BY THE FIRST SUPPLEMENTAL RECORD OF\nSURVEY RECORDED AS ENTRY NO. 289073.", "document_type": "GRANT DEED", "accept": true }, "errorMessage": null }

Purchase and Sale Agreement

Purchase and Sale Agreement entities are returned as a JSON object.

View or hide the expected JSON response

{ "message": "OK", "requestId": "your-requestId-here", "response": { "entities": [ { "text": "Wei Dai", "type": "PERSON", "words": [ { "line_id": "cc1b9b54-4f93-4fbb-8a8a-008ca21798e3", "word_text": "Wei", "page_number": 1, "bounding_box": { "top": 0.07234074175357819, "left": 0.35113614797592163, "width": 0.11444901674985886, "height": 0.02534463070333004 }, "ocr_confidence": 0.9958470153808594 }, { "line_id": "e82fc871-ceeb-40ea-8814-bf2a6131298e", "word_text": "Dai", "page_number": 1, "bounding_box": { "top": 0.07218379527330399, "left": 0.5029894709587097, "width": 0.14778336882591248, "height": 0.03146405518054962 }, "ocr_confidence": 0.997081527709961 } ], "span_end": 16, "span_start": 0, "ai_confidence": 0.8763666152954102 }, { "text": "Snow", "type": "ORGANIZATION", "words": [ { "line_id": "996f388d-60d7-423d-bc04-39087cdb5e3f", "word_text": "Snow", "page_number": 1, "bounding_box": { "top": 0.1112598404288292, "left": 0.3497231602668762, "width": 0.0423760712146759, "height": 0.016683269292116165 }, "ocr_confidence": 0.9993796539306641 } ], "span_end": 21, "span_start": 17, "ai_confidence": 0.49930137395858765 }, etc. ], "raw_text": "Lorem ipsum dolor sit amet...", "num_pages": 17, "request_id": "your-requestId-here" }, "errorMessage": null }

Rent Roll

Rent Roll data groups are returned as a JSON object, and, if your subscription includes it, may return a .csv file as well.

View or hide the expected JSON response

{ "message": "OK", "requestId": "your-requestId-here", "response": { "type": "object", "properties": { "Unit": "01", "Tags": "Furnished, New heater", "BD/BA": "3/1.50", "Tenant": "Satoshi Nakamoto", "Status": "Current", "Sq. Ft.": "1080", "Market Rent": "1,650.00", "Rent": "1,250.00", "Deposit": "1,250.00", "Lease From": "07/31/2016", "Lease To": "07/30/2021", "Move-in": "07/31/2016", "Move-out": "", "Past Due": "0.00", "NSF Count": "0", "Late Count": "0", "_unit_num": "01", "_sqft": 1080.0, "_bed_count": 3.0, "_bath_count": 1.5, "_market_rent": 1650.0, "_real_rent": 1250.0, "_move_in_date": "2016-07-31" } }, "errorMessage": null }

Errors

The BlueSuit API uses the following error codes (also described above):

HTTP Status Code	Description
400	Bad Request
404	Not Found
500	Internal Server Error

Changelog

This is a list of changes to the ExtractAPI.

April 16, 2021

Breaking

New header-authetication requirements for sending requests to the server. This change requires you to use '"x-api-key"' instead of '"Authentication: Bearer"' in the header.

New

Implemented rate limiting on user-to-server requests. Previously there was no limit.

New

Added additional document endpoints - more document types, and the ability to send documents for quick processing, and accuracy-focused processing.