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"
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.
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"
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":Overview Data: View or hide the expected JSON response
"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.
{
"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
}
View or hide the expected JSON response
Purchase and Sale Agreement
Purchase and Sale Agreement entities are returned as a JSON object.
{
"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
}
View or hide the expected JSON response
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.
{
"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
}
View or hide the expected JSON response
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.