Create a New Home Lending Application

Overview

The following section will walk you through creating a new Home Lending Application in Blend using Blend's Public API.

The most common use case for this workflow is where a lead is collected in a CRM or LOS system prior to Blend, but Blend is intended to be the main portal for the borrower to complete the application process.

Routes

POST home-lending/applications - create a new home lending application with the primary borrower party
POST /parties - add any additional coborrower parties to the application
GET /lenders - retrieve information on Employees available to assign to applications in Blend
PUT home-lending/applications/id/assignees - assign a set of employees to an application

1. Create an Application with the Primary Borrower Party

POST home-lending/applications - Request

The following example will walk you through creating a Purchase Home Lending Application in Blend.

For the complete technical documentation on this route, please see the API Schema Reference: TODO add link to new reference

Key Required Fields

The only information required to create a new Home Lending Application is the Name and Email of the Primary Borrower Party.

curl -X POST \
'https://api.beta.blendlabs.com/home-lending/applications' \
-H '[Required Blend Headers - See the Quick Start Guide: https://developers.blend.com/blend/docs]' \
-d '{
  "party":{
    "email":"[email protected]",
    "name":{
      "firstName":"Britt",
      "lastName":"F"}
    },
  }'

However, there are many other options available when creating a new application.

HIGHLY RECOMMENDED: Identifying Application Source

If you are creating a new application in Blend from a record in an external system, it is highly recommended that you take full advantage of all the tracking fields Blend exposes to help keep things synced between your systems.

These fields include:

applicationSource.Type - An enumerated value describing if the external source is a CRM, LOS, or Other system.
applicationSource.Name - An string value that can contain the name of the external system in the case when multiple CRMs or LOSs may be integrated
leadId - the lead source that may have generated this lead
losId - the UUID of the application in your LOS
crmId - the UUID of the application in your CRM
referenceNumber - the main "human-friendly" identifier for this application across you systems. Often the same as the LOS UUID, but some LOSs allow for a more readable/rememberable ID to be set for applications as well and that is the purpose of this field. This field can be manually changed in the Blend UI by Employee Users, so it's not recommended to rely on this ID ONLY to connect identity across systems. Instead this ID should always be used in conjunction with the main LOS or CRM ID fields.

Utilizing these fields isn't just valuable for your systems to remain in sync with each other. They are also valuable to your employee teams working in the Blend UI.

Source Type, Source Name, Reference Number and LOS ID are all optional columns and search filters available to them in their pipeline view to use optimize their workflow. We'll cover how this API connects to what users see in the Blend UI more below.

curl -X POST \
'https://api.beta.blendlabs.com/home-lending/applications' \
-H '[Required Blend Headers - See the Quick Start Guide: https://developers.blend.com/blend/docs]' \
-d '{
  "party":{
    "email":"[email protected]",
    "name":{
      "firstName":"Britt",
      "lastName":"F"}
    },
  "applicationSource":{
    "name":"hands",
    "type":"CRM"
  },
  "crmId":"",
  "leadId":"",
  "losId": "",
  "referenceNumber": ""
}'

Recommended: Borrower Party Experience Controls

There are also many options available when creating a new application via the API to determine the experience borrower parties will have in Blend.

Borrower Experience Control Fields:

solutionSubtype - The Solution Type is Home Lending (determined by the API route). This field specifies what subtype of Home Lending this application is for. For example, "HELOC" or "HELOAN".
applicationExperienceType - Determines if the borrowers will complete the full application in Blend, or if they will only complete post-submissions activities in Blend, e.g. Disclosures.
loanPurposeType - Indicates if this is a new Purchase or Refinance application.
applicationTemplateID - allows the Borrowers to be directed to a specific application flow template in the case where a Blend customer may have multiple templates defined for the same solution Subtype and or Loan Purpose Type.
sendEmailInvite - Determines if the primary borrower party included in the POST request will automatically be send an invite from Blend upon creation or not.
redirect - Indicates if this call is the prerequisite for an automatic redirect of the borrower into the Blend UI to complete this application. Causes the magic redirect login link that is usually included in the invite email to be returned in the API response instead with only a 10 minute TTL. See https://developers.blend.com/blend/docs/redirect-urls-for-consumer-experience-integrations for more information on this use case.

curl -X POST \
'https://api.beta.blendlabs.com/home-lending/applications' \
-H '[Required Blend Headers - See the Quick Start Guide: https://developers.blend.com/blend/docs]' \
-d '{
  "party": {
    "type": "BORROWER",
    "name": {
      "firstName": "",
      "lastName": ""
      },
    "email": ""
    },
  "solutionSubType": "MORTGAGE",
  "applicationExperienceType": "FULL_APPLICATION",
  "loanPurposeType": "PURCHASE",
  "applicationTemplateId": "fd658b97-f901-4b14-b693-4654d276c909"
  "sendEmailInvite": true,
  "redirect": true
}'

Other Optional Fields

The POST home-lending/applications route also allows information on the loan amount, the property, and additional information about the primary borrower party to be set at application creation time.

curl -X POST \
'https://api.beta.blendlabs.com/home-lending/applications' \
-H '[Required Blend Headers - See the Quick Start Guide: https://developers.blend.com/blend/docs]' \
-d '{
  "party": {
    "name": {
      "firstName": "",
      "middleName": "",
      "lastName": "",
      "suffix": ""
      },
    "email": "",
    "dateOfBirth": "",
    "taxpayerIdentifier": {
      "type": "",
      "value": "",
      },
    "phoneNumber":{
      "type": "",
      "value": "",
      },
    "currentAddress": {
      "streetAddressLine1": "",
      "streetAddressLine2": "",
      "city": "",
      "state": "",
      "zipCode": "",
      "zipCodePlusFour": ""
      },
    }'
  "property":, {
    "propertyAddress": {
      "streetAddressLine1": "",
      "streetAddressLine2": "",
      "city": "",
      "state": "",
      "zipCode": "",
      "zipCodePlusFour": ""
      },
    "propertyType": "SINGLE_FAMILY",
    "propertySearchType": "NOT_STARTED",
    "propertyUsageType": "PRIMARY_RESIDENCE",
    "propertyValue": 123,
  },
  "loanAmount": 123,
  "communityId": 123  
}'

POST home-lending/applications - Response

If successful, the returned response will have a few key fields as well.

id - Blend Application ID: a unique identifier generated by Blend to identify the application. It is especially important that you hang on to this ID in the immediate-term, because you will need it in subsequent calls to add additional parties to the application, and/or assign the application to employees.
party.id Blend Party ID: a unique identifier generated by Blend to identify this party in relation to this application.

{
  "id":"0294dbd5-59b5-48c4-94f1-1d836f37f836"
  "solutionSubType":""
  "parties":[
    0:{
      "id":"8fd027ed-3b68-4f86-8976-8b023dfe4a9c"
      "name":{
        "firstName":""
        "lastName":""
      }
      "type":"BORROWER"
    }
  ]
}

What you can expect to see in the Blend Employee UI

After the application is created via the API, you should be able to see the application in your Blend Pipeline if you have permissions to see all applications in Blend, or if you are assigned to the application (more on assigning applications below). You can also look up the application with the application ID from the POST Response using the search function.

In the Blend Application page, the following information will be carried over to the application:

2. Add Additional Parties

If you application involves more than one borrower, or other associated parties, like realtors, you can add additional parties once the initial application has been created in Blend

POST /parties - Request

curl -X POST \
'https://api.beta.blendlabs.com/parties' \
-H '[Required Blend Headers - See the Quick Start Guide: https://developers.blend.com/blend/docs]' \
-d '{
   "applicationId": "e92ef01b-9ed0-45af-b5ab-d0ae949ba765"
   "name": {
     "firstName": "",
     "middleName": "",
     "lastName": "",
     "suffix": ""
   },
   "email": "",
   "dateOfBirth": "",
   "taxpayerIdentifier": {
     "type": "",
     "value": "",
   },
   "phoneNumber":{
     "type": "",
     "value": "",
   },
   "currentAddress": {
     "streetAddressLine1": "",
     "streetAddressLine2": "",
     "city": "",
     "state": "",
     "zipCode": "",
     "zipCodePlusFour": ""
   },
   "econsent': {
     "date": ""
     "ip": ""
     "status": ""
   },
   "losPartyId": "" 
   "type": "COBORROWER",
   "verificationData": {
     "code": ""
     "hint": ""
   }
}'


'{"applicationId":"0294dbd5-59b5-48c4-94f1-1d836f37f836","currentAddress":{"city":"Russell","state":"KS","streetAddressLine1":"1095 S. Southside Dr","zipCode":"67665"},"email":"[email protected]","name":{"firstName":"David","lastName":"Fritsch"},"type":"COBORROWER"}'

Considerations when adding additional borrower parties:

*Provide a FNMA/1003 file location for borrowers

1003 number and position number so that we can add the borrower into the correct 1003.
- Example: {"fileNumber":1, "filePosition" 2} will add a co-borrower to 1003 form 1
- Example: {"fileNumber":2, "filePosition" 1} will add a borrower to 1003 form 2

Application Change Locks
For most Blend customers, your settings will only allow additional borrower parties to be added to the application when:

The primary borrower party has not yet accepted their application invitation
The application has not yet been marked as exported (to the LOS or other integration)

POST /parties - Response

{
  "id":"0cc2ea58-b788-4ce2-8636-396398cfdc31"
  "type":"COBORROWER"
  "name":{
    "firstName":"David"
    "lastName":"Fritsch"
  }
  "email":"[email protected]"
  "econsent":{
    "status":"Pending"
    "date":NULL
    "ip":NULL
  }
  "applicationId":"0294dbd5-59b5-48c4-94f1-1d836f37f836"
}

What you can expect to see in the Blend Employee UI

Application page:

Additionally, once an application has been created, additional actions taken on that application will be visible in the Applications activity log.

Application activity log:

3. Assign the Application to an Employee User

Once you've successfully created an application, you'll likely want to assign it to a set of team members.

It's most efficient if you can store the Blend User UUID of your employees in your Identity Provider or other store that will determine application assignment. If you are able to do that then you can skip the GET /lenders steps below and proceed directly to assigning the application.

GET /lenders - Request

In order to assign the application to Blend Employee Users, you will need their Blend User ID. If you do not have the IDs on hand, you can retrieve them from Blend via the GET /lenders route by querying by their emails.

curl -X GET \
'https://api.beta.blendlabs.com/lenders?emails=email1%2Cemail2%2Cemail3' \
-H '[Required Blend Headers - See the Quick Start Guide: https://developers.blend.com/blend/docs]' \

GET /lenders - Response

"success":[
  0:{
    "email":""
    "loginMethod":""
    "id":"36f34741-08cf-4dd5-a3f6-d6f31c243784"
    "status":""
    "name":""
    "permittedSolutionSubTypes":[
      0:"HELOAN"
      1:"HELOC"
      2:"MORTGAGE"
      3:"CANADA_MORTGAGE"
      4:"ACCOUNT_OPENING"
      5:"AUTO"
      6:"OTHER"
    ]
    "requireTwoFactorAuth": 
    "roleNames":[
      0:""
    ]
  }
]

PUT home-lending/applications/id/assignees - Request

You will need to replace the "id" in this route with the UUID of the Blend Application you want to assign employees to.

This route accepts an array of assignee objects that include the Blend User UUID of the Employee and their assignment role (whether they are the primary assignee or not).

curl -X PUT \
'https://api.beta.blendlabs.com/home-lending/applications/[id]/assignees' \
-H '[Required Blend Headers - See the Quick Start Guide: https://developers.blend.com/blend/docs]' \
-d '{
  "assignees":[
    {
      "role":"PRIMARY_ASSIGNEE",
      "userId":"36f34741-08cf-4dd5-a3f6-d6f31c243784"
    },
    {
      "role":"ASSIGNEE",
      "userId":"6f41ac99-75ab-43d2-90db-cab7360e428d"
    }
  ]
}'

What you can expect to see in the Blend Employee UI

Once the application has been assigned via the API, it will appear as having a user assigned to it in the Pipeline and in the Header throughout the Application view.

Pipeline view:

Header in the Application View:

🚧
Application Header View not Generally Available until mid-November 2019
The screenshot below is 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.