shell

Introduction

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

We've made some big changes

As of July 14, 2022 - the BlueSuit ExtractAPI has been significantly changed in order to accept documents of all sizes. Our overview below outlines the new steps for submitting documents and receiving results from our API.

Need to reference the old version? Read the old documentation. Please note that this documentation contains instructions for the older version of our API and should not be used for updating or creating new integrations. This version will be fully sunset in 6 months; by January 13, 2023.

Get Started

This is a general overview of the process of submitting a document to our system for extraction, checking the status, and retrieving the response. Details and code snippets are futher below.

  1. Get your API key from your BlueSuit dashboard. Note: Your API key must be included in all API requests sent to the server.
  2. Request a document upload.
  3. Submit your document. Note: Our API is rate limited.
  4. Kick off the process of extracting data from your document. Note: Our API is asynchronous and may take several minutes for results to be available.
  5. Check on the status of the extraction.
  6. Once your data is ready, you may use the response route directly, or your status endpoint will return a redirect to the response.

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.

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 as follow:

"x-api-key: [PutYourSpecialAPIKeyHereIfYouWantThisToWork]"

To authorize, use this code:

-H "x-api-key: [PutYourSpecialAPIKeyHereIfYouWantThisToWork]"

Send Documents (POST)

Step 1

POST to the ExtractAPI URL and save your returned uploadId and uploadUrl.

HTTP Request

curl -X POST "https://extract.bluesuit.com/v1/upload" \
-H "Content-Type: application/json" \
-H "x-api-key:[PutYourSpecialAPIKeyHereIfYouWantThisToWork]"

This will return your uploadId and uploadUrl.

Step 2

POST your document file to your uploadUrl from the response in Step 1.

curl -X POST [Your Upload URL] \
  -F "--upload-file=@\"/path/to/file\"" \

Step 3

This will return your requestId

Once you have finished uploading the document, build your RequestConfig, and POST it to [/YOUR-ROUTE] and save your requestId.

RequestConfig must always have uploadId and mode. You will also have the option to add additional, optional properties.

Required Properties

Property Description
route API route you wish to send your document to
mode Specify which processing mode you wish to trigger

Required Properties | Document Routes

Route Description
closing_disclosure Closing Disclosure documents
property_deed Property Deed documents
rent_roll Rent Roll documents
psa Purchase and Sale Agreement documents (data returned as entities)
offering_memo Offering Memo documents
title_search_package Full Title Search Package

Required Properties | Processing Modes

Each mode offers a different type of processing.

Choosing accurate or foundational may greatly increase the response time.

Mode Description
quick Fastest response, sends your document directly to the model.
accurate Sends the document to the model and then a human-in-the-loop for review
foundational Sends the document directly to the model with non-contextual data points returned

Our API allows for some additional information to be passed along to help tailor your experience. You may add a tag, the source language, and one or more email addresses that will recieve a copy of the final data to your request.

curl -X POST "https://extract.bluesuit.com/v1/[YOUR-ROUTE]” \
  -H "x-api-key: [YOUR-API-KEY]” \
  -H "Content-Type: application/json" \
  -d "{ 
        \"mode\": \"quick\", 
        \"uploadId\": \”[UPLOAD-ID]\”, 
      }"

Optional Properties

Property Data Type Description
email [String] Specify email addresses you wish to have final data sent to. Specify them as comma-seperated lists if you wish to send the results to multiple email addresses.
tag String Specify an arbitrary request tag that is stored in our system. You may use this as an identifier from external systems.
sourcelang String Specify the source programming language from which the request was sent

An example of STEP 3 with all required and optional properties.

curl -X POST "https://extract.bluesuit.com/v1/[YOUR-ROUTE]” \
  -H "x-api-key: [YOUR-API-KEY]” \
  -H "Content-Type: application/json" \
  -d "{ 
        \"mode\": \"quick\", 
        \"uploadId\": \”[UPLOAD-ID]\”, 
        \"email\": [\”email@email.com\"],
        \"tag\": \"test-tag\", 
        \"sourcelang\": \"curl\" 
      }"

Check Status

When you start processing a document, you will be given a requestId (a UUIDv4) to reference in the JSON data returned from the endpoint. Additionally, the location header of the successful HTTP 202 response will point you to a status endpoint you can poll to monitor the status of your request.

Due to our asynchronous process, the response may take several minutes before it's ready to retrieve. While you are waiting, you can check on the status of our extraction process by polling the status endpoint returned by the previous step. The status endpoint will continue to return an HTTP 202 until the document has finished processing.

HTTP Request

  curl -H "x-api-key: [PutYourSpecialAPIKeyHereIfYouWantThisToWork]" \
    "https://extract.bluesuit.com/v0/status?requestId=[put-your-requestId-here]"

THE ABOVE COMMAND WILL RETURN THIS MESSAGE WHEN YOUR DOCUMENT HAS BEEN ACCEPTED:

{
  "message": "Accepted",
  "requestId": "0cf8at76-s567-485a-91r7-e7o254ka06y8"
}

ONCE YOUR DOCUMEMT HAS FINISHED PROCESSING, YOU WILL SEE THIS MESSAGE WHEN YOU CHECK THE STATUS:

{
  "message": "Found",
  "requestId": "0cf8at76-s567-485a-91r7-e7o254ka06y8"
}

Use this URL to get the status of your document extraction.

"https://extract.bluesuit.com/v0/status?requestId=[put-your-requestId-here]"

HTTP Status Codes

Status Code Description Meaning
202 Accepted Your document is being processed
302 Found Your results are ready
400 Error Bad Request
404 Error Not Found
422 Error There was an extraction error
429 Warning Too many requests. You may have exceeded the Rate Limit - please wait a few minutes and try again.
500 Error Internal Server Error

Retrieve Results (GET)

curl -H "x-api-key: [YOUR-API-KEY]” /
“https://extract.bluesuit.com.com/v1/response?requestId=[YOUR-REQUEST-ID]”

Once you see "message": "Found", you can request your results using the following URL.

HTTP Request

"https://extract.bluesuit.com/v0/result?requestId=[put-your-id-here]"

Success Response

A successful response will include the document-specific data within the response. For examples of the document-specific results that will populate response, go to Sample Responses by Document.

An example payload from /response in the event of a success

{
  "message": "OK",
    "requestId": "00000000-0000-0000-0000-000000000000",
    "response": {
      "fieldGroup": {
        "accuracyIQ": "pass",
        "field1": "some",
        "field2": "data"
        }
    },
  "errorMessage": null
}

Failure Response

If your POST was successful, but the extraction itself failed, you will see a failure response.

An example payload from /response in the event of a failure

{
  "message": "OK",
  "requestId": "00000000-0000-0000-0000-000000000000",
  "response": null,
  "errorMessage": "Your document could not be processed"
}

Sample Responses by Document

AccuracyIQ

This is what a typical response for AccuracyIQ will look like. You will see either a fail or pass in the response. 

  {
    "accuracyIQ: 'pass'",
  }

Closing Disclosure

Closing Disclosure data groups are returned as a JSON object.

/CLOSING_DISCLOSURE RETURN JSON STRUCTURED LIKE THIS

{
  "indexingAndClassification": {
    "accuracyIQ": "pass",
    "additionalDocs": false,
    "deed1Start": 1,
    "deed2Start": null,
    "deed3Start": null,
    "deed4Start": null,
    "deed5Start": null,
    "deed6Start": null,
    "deed1End": 8,
    "deed2End": null,
    "deed3End": null,
    "deed4End": null,
    "deed5End": null,
    "deed6End": null,
    "mortgage1Start": 9,
    "mortgage2Start": null,
    "mortgage3Start": null,
    "mortgage4Start": null,
    "mortgage5Start": null,
    "mortgage6Start": null,
    "mortgage1End": 22,
    "mortgage2End": null,
    "mortgage3End": null,
    "mortgage4End": null,
    "mortgage5End": null,
    "mortgage6End": null,
    "aom1Start": null,
    "aom2Start": null,
    "aom3Start": null,
    "aom4Start": null,
    "aom5Start": null,
    "aom6Start": null,
    "aom1End": null,
    "aom2End": null,
    "aom3End": null,
    "aom4End": null,
    "aom5End": null,
    "aom6End": null
  },
  "legalDescription": {
    "legalDescription": "Lot 33, SAUK MOUNTAIN VIEW ESTATES SOUTH - A PLANNED RESIDENTIAL DEVELOPMENT PHASE 3, according to the plat thereof, recorded May 25, 2005, under Auditor's File No. 200505260107, records of Skagit County, Washington",
    "accuracyIQ": "pass"
  },
  "deed1": {
    "accuracyIQ": "pass",
    "grantor": "Jeffrey S Daily and Kristina D Daily, husband and wife",
    "grantee": "Gilberto Deleon, Jr. and Jennifer Michael Deleon, husband and wife and Cindy Louise Smith, an unmarried person as her separate estate",
    "recordedDate": "2012-11-20 00:00:00",
    "executedDate": "2012-11-09 00:00:00",
    "instrumentNumber": "201211140056",
    "bookPageNumber": null,
    "consideration": "10.0",
    "documentType": "STATUTORY WARRANTY DEED"
  },
  "deed2": {
    "accuracyIQ": "fail",
    "grantor": null,
    "grantee": null,
    "recordedDate": null,
    "executedDate": null,
    "instrumentNumber": null,
    "bookPageNumber": null,
    "consideration": null,
    "documentType": null
  },
  "deed3": {
    "accuracyIQ": "fail",
    "grantor": null,
    "grantee": null,
    "recordedDate": null,
    "executedDate": null,
    "instrumentNumber": null,
    "bookPageNumber": null,
    "consideration": null,
    "documentType": null
  },
  "deed4": {
    "accuracyIQ": "fail",
    "grantor": null,
    "grantee": null,
    "recordedDate": null,
    "executedDate": null,
    "instrumentNumber": null,
    "bookPageNumber": null,
    "consideration": null,
    "documentType": null
  },
  "deed5": {
    "accuracyIQ": "fail",
    "grantor": null,
    "grantee": null,
    "recordedDate": null,
    "executedDate": null,
    "instrumentNumber": null,
    "bookPageNumber": null,
    "consideration": null,
    "documentType": null
  },
  "deed6": {
    "accuracyIQ": "fail",
    "grantor": null,
    "grantee": null,
    "recordedDate": null,
    "executedDate": null,
    "instrumentNumber": null,
    "bookPageNumber": null,
    "consideration": null,
    "documentType": null
  },
  "mortgage1": {
    "accuracyIQ": "pass",
    "recordedDate": "2012-11-14 00:00:00",
    "executedDate": "2012-11-08 00:00:00",
    "instrumentNumber": "201211140057",
    "bookPageNumber": null,
    "documentType": "DEED OF TRUST",
    "trustee": "Chicago Title Company.",
    "borrower": "GILBERTO DE LEON JR AND JENNIFER MICHAEL DE LEON, HUSBAND AND WIFE; AND CINDY LOUISE SMITH, AN UNMARRIED PERSON AS HER SEPARATE ESTATE+",
    "lender": "WHIDBEY ISLAND BANK.",
    "loanAmount": 168367,
    "maturityDate": "2042-12-01 00:00:00",
    "mortgageIdentificationNumber": "1002978-1030017361-6"
  },
  "mortgage2": {
    "accuracyIQ": "fail",
    "recordedDate": null,
    "executedDate": null,
    "instrumentNumber": null,
    "bookPageNumber": null,
    "documentType": null,
    "trustee": null,
    "borrower": null,
    "lender": null,
    "loanAmount": null,
    "maturityDate": null,
    "mortgageIdentificationNumber": null
  },
  "mortgage3": {
    "accuracyIQ": "fail",
    "recordedDate": null,
    "executedDate": null,
    "instrumentNumber": null,
    "bookPageNumber": null,
    "documentType": null,
    "trustee": null,
    "borrower": null,
    "lender": null,
    "loanAmount": null,
    "maturityDate": null,
    "mortgageIdentificationNumber": null
  },
  "mortgage4": {
    "accuracyIQ": "fail",
    "recordedDate": null,
    "executedDate": null,
    "instrumentNumber": null,
    "bookPageNumber": null,
    "documentType": null,
    "trustee": null,
    "borrower": null,
    "lender": null,
    "loanAmount": null,
    "maturityDate": null,
    "mortgageIdentificationNumber": null
  },
  "mortgage5": {
    "accuracyIQ": "fail",
    "recordedDate": null,
    "executedDate": null,
    "instrumentNumber": null,
    "bookPageNumber": null,
    "documentType": null,
    "trustee": null,
    "borrower": null,
    "lender": null,
    "loanAmount": null,
    "maturityDate": null,
    "mortgageIdentificationNumber": null
  },
  "mortgage6": {
    "accuracyIQ": "fail",
    "recordedDate": null,
    "executedDate": null,
    "instrumentNumber": null,
    "bookPageNumber": null,
    "documentType": null,
    "trustee": null,
    "borrower": null,
    "lender": null,
    "loanAmount": null,
    "maturityDate": null,
    "mortgageIdentificationNumber": null
  },
  "aom1": {
    "accuracyIQ": "fail",
    "assignor": null,
    "assignee": null,
    "instrumentNumber": null,
    "recordedDate": null,
    "executedDate": null,
    "bookPageNumber": null,
    "documentType": null,
    "trustee": null
  },
  "aom2": {
    "accuracyIQ": "fail",
    "assignor": null,
    "assignee": null,
    "instrumentNumber": null,
    "recordedDate": null,
    "executedDate": null,
    "bookPageNumber": null,
    "documentType": null,
    "trustee": null
  },
  "aom3": {
    "accuracyIQ": "fail",
    "assignor": null,
    "assignee": null,
    "instrumentNumber": null,
    "recordedDate": null,
    "executedDate": null,
    "bookPageNumber": null,
    "documentType": null,
    "trustee": null
  },
  "aom4": {
    "accuracyIQ": "fail",
    "assignor": null,
    "assignee": null,
    "instrumentNumber": null,
    "recordedDate": null,
    "executedDate": null,
    "bookPageNumber": null,
    "documentType": null,
    "trustee": null
  },
  "aom5": {
    "accuracyIQ": "fail",
    "assignor": null,
    "assignee": null,
    "instrumentNumber": null,
    "recordedDate": null,
    "executedDate": null,
    "bookPageNumber": null,
    "documentType": null,
    "trustee": null
  },
  "aom6": {
    "accuracyIQ": "fail",
    "assignor": null,
    "assignee": null,
    "instrumentNumber": null,
    "recordedDate": null,
    "executedDate": null,
    "bookPageNumber": null,
    "documentType": null,
    "trustee": null
  }
}

Offering Memo

Offering memo data groups are returned as a JSON object.

/OFFERING_MEMO RETURN JSON STRUCTURED LIKE THIS:

{
    "property": {
        "accuracyIQ": "pass",
        "askingCapRate": 0.0810,
        "askingPrice": 3150000,
        "brokerEmail": "email@broker.com",
        "priceSF": 716.66,
        "priceUnit": 425142,
        "propertyCity": Buffalo,
        "propertyState": New York,
        "propertyStreetAddress": 1 Bills Drive,
        "propertyType": "multifamily",
        "propertyZipcode": null,
        "squareFootage": 2023,
        "unitCount": 4,
        "yearBuilt": 1968
    },
    "financial": {
        "accuracyIQ": "pass",
        "effectiveGrossRevenue": 959920,
        "netOperatingIncome": 477201,
        "totalExpenses": 52719
    }
}

Property Deeds

Property Deed data groups are returned as a JSON object.

/PROPERTY_DEEDS RETURN JSON STRUCTURED LIKE THIS:

{
    "legalDescription": {
        "accuracyIQ": "pass",
        "legalDescription": "Lot Number Ten (10) of Dickens Heights Subdivision, Section 42, as the same is\nrecorded in Cherry Cabinet 7, Slide 346 of the Queens County, New York records."
    },
    "basic": {
        "accuracyIQ": "pass",
        "bookPageNumber": "['123', '4567']",
        "consideration": "100.0",
        "documentType": "PROPERTY DEED",
        "executedDate": "2014-12-02 00:00:00",
        "grantee": "Stefon Diggs",
        "grantor": "Josh Allen, an unmarried man",
        "instrumentNumber": "20141202000011234567",
        "recordedDate": "2014-12-02 00:00:00"
    }
}

Purchase and Sale Agreements

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

/PSA/FOUNDATIONAL RETURN JSON STRUCTURED LIKE THIS:

    {
        "ai_confidence": 0.9759599268436432,
        "span_end": 73,
        "span_start": 66,
        "text": "WEI DAI, LTD",
        "type": "ORGANIZATION",
        "words": [
            {
                "bounding_box": {
                    "height": 0.010670654475688934,
                    "left": 0.461274117231369,
                    "top": 0.44382479786872864,
                    "width": 0.039836786687374115
                },
                "line_id": "34hgnks-sad0-4536-6346-a3489a89886b",
                "ocr_confidence": 0.9967111206054687,
                "page_number": 1,
                "word_text": "WEI"
            },
        ... 
        ]
    }

/PSA/QUICK RETURN JSON STRUCTURED LIKE THIS: shell { "basic": { "accuracyIQ": "pass", "buyerName": "Josh Allen", "sellerName": "First Buffalo Energy L.L.P", "purchasePrice": 234567, "propertyStreet": "1 Bills Drive", "propertyCity": "Buffalo", "propertyState": "New York", "propertyZipcode": "14222" }, "participants": { "accuracyIQ": "pass", "buyerBroker": "Stefon Diggs", "sellerBroker": "Wyoming Land Ltd", "buyerAttorney": "Von Miller", "sellerAttorney": "Sean McDermott", "titleCompany": "Liberty City Title Insurance Company", "titleAgent": "" }, "earnestMoney": { "accuracyIQ": "pass", "additionalEarnestMoney": null, "initialEarnestMoney": 12345 }, "legalDescription": { "accuracyIQ": "pass", "legalDescription": "Lot 42, Block 3, of Great Lakes Subdivision #1, according to map or plat thereof as recorded in Plat Book 17, Page 23, of the Public Records of Erie County, New York." }, "dates": { "accuracyIQ": "pass", "closingDate": "fifteen (15) days after the last day of the Inspection Period", "effectiveDate": "" } }

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.

/RENT_ROLLS RETURN JSON STRUCTURED LIKE THIS:

  "multifamily": {
        "accuracyIQ": "pass",
        "rows": [
            {
                "bathCount": null,
                "bedCount": null,
                "marketRent": 780,
                "moveInDate": "2008-08-01",
                "realRent": 1250,
                "rowIdentifier": "row1",
                "sqft": 625,
                "unitNumber": "3L",
                "unitType": "flat_b",
                "key": "--564-2008-08-01-1250-row1-625-3L-flat_b-0"
            },
           ... 
        ]
      }

  "raw": {
        "accuracyIQ": "pass",
        "rows": [
            {
                "Actual Rent": "1250.00",
                "Balance": "1250.00",
                "Lease Expiration": "01/31/2020",
                "Market Rent": "1900.00",
                "Move In": "08/01/2008",
                "Move out": "",
                "Name": "Josh Allen",
                "Other Deposits": "1250.00",
                "Resident": "t458345",
                "Resident Deposit": "0.00",
                "Unit": "3L",
                "Unit Sq Ft": "625",
                "Unit type": "flat_b",
                "_hud": "",
                "_market_rent": 1900,
                "_move_in_date": "2008-08-01",
                "_real_rent": 1250,
                "_sqft": 625,
                "_unit_num": "3L",
                "_unit_type_string": "flat_b",
                "_vacant": "",
                "rowIdentifier": "row0",
                "key": "1250.00-1900.00-01/31/2020-1250.00-08/01/2008--Josh Allen-0.00-458345-3L-625-flat_b--1250-2008-08-01-1250-625-3L-flat_b--row0-0"
            },
        ]
  }

Errors and Warnings

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

HTTP Status Code Description
400 Bad Request
404 Not Found
422 Error - There was an extraction error.
429 Warning - Too many requests. You may have exceeded the Rate Limit - please wait a few minutes and try again.
500 Internal Server Error

Changelog

July 12, 2022

New Version

New Version of the API has been launched.

November 15, 2021

New

Updated language to clarify the POST process, and adding notice about the impending Beta for ExtractAPI.

May 19, 2021

New

Added a new document route to the API for Offering Memos.

April 30, 2021

New

Rent roll extracted results may now be downloaded in diffeent formats with the addition of query string parameters.

New

Rent roll results now include a _vacant variable in the results.

April 27, 2021

New

Rent roll extracted results may now be tagged and sent to an email address with the addition of query string parameters.

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.

shell