HomeGuidesAPI ReferenceChangelogDiscussions
GuidesAPI ReferenceDiscussions

Export a Home Lending Application

Overview

The following sections will show you how to export the industry-standard mortgage loan application files from Blend using the Blend Public API. This guide will include how to know an application is ready to be exported, how to export the application file, and how to update the Blend Application Export Status throughout the export process.

Note that for integration use cases other than "exporting" the full application file, much of the same application information is available in a JSON object from the GET home-lending/applications/id route. This guide will focus specifically on the full-file export use case.

For instructions on exporting Documents other than the core application file from Blend, please refer to the Export Documents reference.

Routes

  • GET home-lending/applications/id/file-export
  • GET home-lending/applications/export-statuses
  • POST home-lending/applications/id/export-status

Prerequisite: Determine when to Export an Application File

Blend will update the status of an application whenever it's exportable. We recommend you use the GET /loans endpoint to see which applications meet your export criteria.

When does Blend update an application's status to 'exportable'?

  1. The borrower party(s) submits their application in Blend
  2. An employee user in Blend clicks 'Export' in the application's Overview page
  3. TRID is triggered (if applicable)

Once an application has been marked as exportable, there are two ways to determine that information.

  1. Use the "exportable=true" query parameter on the GET home-lending/applications route
  2. Be integrated with Blend's webhook event notifications and receive an application event

GET home-lending/applications - Request

🚧

Using the losId to determine exportability

Some Blend partners and customers find it helpful to also utilize the losid-exists query parameter to more precisely determine export status when retrieving applications for export via the API.
If you integration cannot ensure idempotency and you are concerned about duplicate applications being created in the downstream integrated system you are sending the Blend application to, then we recommend you utilize this query parameter as well, when determining exportability.
We'll cover how to complete this integration path in more detail in later steps in this guide.

-- Without additional losid query parameter

curl -X GET \
'https://api.beta.blendlabs.com/home-lending/applications?exportable=true' \
-H '[Required Blend Headers - See the Quick Start Guide: https://developers.blend.com/blend/docs]'

-- With additional losid query parameter

curl -X GET \
'https://api.beta.blendlabs.com/home-lending/applications?exportable=true&losId-exists=false' \
-H '[Required Blend Headers - See the Quick Start Guide: https://developers.blend.com/blend/docs]'

Application Event indicating Export

For an Example Application Event see: TODO link to updated event docs

1. Export Application File From Blend

Once you know which application(s) are ready for export, you are ready to use Blend's Public API to retrieve their application files.

Blend facilitates getting an application file in two formats:

  • Fannie Mae
    • Version 3.2
  • MISMO
    • Version 3.3.1
    • Version 3.4 (BETA ONLY)

Any application can be retrieved in BOTH the FNMA or MISMO format (except if it's a new URLA/MISMO 3.4 loan), but applications can only be retrieved in EITHER the MISMO 3.3.1 or 3.4 format.

  • New URLA loans do not support the FNMA 3.2 format

The MISMO version is determined by an all-applications wide setting in your company's Blend instance.

Whether you retrieve the FNMA or MISMO file is determined by a the "format" query parameter passed in your API call.

GET home-lending/applications/id/file-export?format= - Request

curl -X GET \
'https://api.beta.blendlabs.com/home-lending/applications/id/file-export?format=[fannie-mae or mismo]' \
-H '[Required Blend Headers - See the Quick Start Guide: https://developers.blend.com/blend/docs]'

GET home-lending/applications/id/file-export?format= - Response

The file returned to you will be UTF-8 encoded.

2. Update the application's export status in Blend

The Blend API allows updating an application export status in Blend via the POST home-lending/applications/id/export-status route.

👍

Why is this important?

Updating an application's export status aids in managing your integration workflow and quickly reconciling any inconsistencies between the two systems that may results from unexpected software issues so that they do not ultimately impact your business processes.

Export Status Definitions

  • FAILED: The application didn't export as expected and export should be attempted again.
  • IN_PROGRESS: The external system has begun an attempt to export this application, and no other attempts should be started at this time. Also freezes the ability to make changes in Blend until the export attempt has finished.
  • SUCCESS - The application has been exported from Blend and uploaded to the external system successfully.

It is always a good idea to GET the export status of an application before updating its status, in order to ensure the status is in the state you expect it to be in.

GET home-lending/applications/export-statuses - Request

curl -X GET \
'https://api.beta.blendlabs.com/home-lending/applications/export-statuses?ids=0294dbd5-59b5-48c4-94f1-1d836f37f836' \
-H '[Required Blend Headers - See the Quick Start Guide: https://developers.blend.com/blend/docs]'

GET home-lending/applications/export-statuses - Response

{
  "success":[
    0:{
      "applicationId":"0294dbd5-59b5-48c4-94f1-1d836f37f836"
      "status":"UNABLE_TO_EXPORT"
    }
  ]
}

Once you have ensured the export-status is in the state you expect it to be in, then you can update the export status for the application.

In addition to posting the status, you can also post a reason for the status. This is especially useful in case of an error in a downstream system to help the Employee users of Blend understand what happened and if there is anything they can do to fix it, or if it requires some other kind of intervention.

GET home-lending/applications/export-status - Request

curl -X POST \
'https://api.beta.blendlabs.com/loans/id/export-status' \
-H '[Required Blend Headers - See the Quick Start Guide: https://developers.blend.com/blend/docs]'
-d '{
  "applicationId":"0294dbd5-59b5-48c4-94f1-1d836f37f836",
  "lastUpdated":"",
  "reason":"",
  "status":"IN_PROGRESS"
}'

What you can expect to see in the Blend Employee UI

🚧

Application Header View not Generally Available until mid-November 2019

The screenshots below are from Blend's new "Loan Header" view which will soon replace the previous "Overview" Page.

This new view will be available for all customer's to implement in mid-November 2019, but may not be configured ON in your Blend instance until a later date.

For examples of where to find this information in the previous Overview page, please see this guide in v2.3.0 docs or before.

Upon response, the LOS export status in Blend will update in the Application View Header.

379379

Should any export 'reason' be provided, it will appear in the UI when hovering over the Export icon in the Application View Header.

19181918

3. Recommended Post-Export Steps

In addition to updating the export-status to SUCCESS, there are additional recommended steps when exporting to your LOS specifically.

We recommend that you update the application with an LOS primary key after you have successfully exported it to your LOS.

This will allow you to ensure that no duplicate applications are created down stream in your LOS.

PATCH home-lending/applications/id - Request

curl -X PATCH \
'https://api.beta.blendlabs.com/home-lending/applications/id' \
-H '[Required Blend Headers - See the Quick Start Guide: https://developers.blend.com/blend/docs]'
-d '{
"losId": ""
}'

What you can expect to see in the Blend Employee UI

The LOS ID will now be available to search and sort by in the Employee Pipeline View as "LOS Primary Key".

This data update will also be noted on the Application's Activity log.

Pipeline:

421421

Activity:

13731373