v4.0.0 Upgrade Guide
For the complete and simple summary of the changes below see the v4.0.0 Changelog.
This document is for users of Blend's APIs to help you understand:
- Changes that impact the behavior of the API in this version
- New features and functionality that are available to you in v4.0.0
Please note the v2.x.x will not be supported as of November, 30, 2021.
We've moved the date as a result of conversations with our customer base.
Major Improvements in v4.0.0
The organization of data and routes makes it easier and obvious how to add support for new features or data sets.
Richer Data Sets
Across multiple routes, additional fields have been added to provide depth and richness to a variety of operations in Blend
Consolidation of redundant endpoints
For ease of accessibility, overlapping reports have been consolidated around themes - more data surfaced in one individual report to maximize efficiency.
To fully support a variety of reporting use cases and to offer increased flexibility, reports now have the capability to filter on multiple timestamps instead of a single default timestamp.
Additionally, users can now pass in a dynamic time range when downloading data from batch reports (e.g. data around lender statistics and follow ups metrics).
Additional transparency around who is doing what
We recognize the need to measure adoption around specific features; we’ve enhanced certain reports with fields containing more detailed information on the type of users completing actions (lender vs borrower vs system), as well as added a net new PAB Activities endpoint with granular information.
Behavior changes to application assignees
- /PUT/home-lending/applications/:id/assignees will always use loan teams by default
- Added a query parameter "autoAssignLoanTeam" to disable use of loan teams
- We are changing this route to always respect loan teams irrespective of whether the primary assignee has changed.
Behavior changes to /home-lending/applications
- /PATCH/home-lending/applications/:id allows for partial addresses
- Originally, if a partial address was passed in, a 400 error would be thrown. That has been since relaxed and we now honor the partial address
Consolidation of information around Loans and Lenders
Multiple separate reports with overlapping data have now been consolidated into single reports around themes:
- Loans (Basic Loan Data) now contains additional fields from Loan Pipeline, Loan Statistics, Unassigned Loans
- Lenders (Lender Users) now contains comprehensive lender user metrics with data from Lender Stats, Lender Batch Statistics, and Follow Ups Usage.
- Borrower Application Funnel - this data can be derived from Borrower Workflows
As a result, the following reports have been fully deprecated:
- Loan Pipeline
- Loan Statistics
- Unassigned Loans
- Lender Stats
- Lender Batch Statistics
- Follow Ups Usage
- Borrower Application Funnel
Please see the V4 Data Dictionary/Transition Doc for where to find fields previously contained in these reports.
Increased capabilities for query parameters
Users will now be able to pass in multiple timestamps in the query parameters to filter on different events.
For example - for the Loans (Basic Loan Data) endpoint in 2.x.x-3.x.x, the previous start and end date parameters defaulted to the event timestamp for Loan Last Updated. Users can now specify which event to filter on (chaining allowed), including:
- Loan Created
- Borrower Started
- Borrower Submitted
- Loan Exported
- Loan Deleted
- Loan Archived
- Loan Purged
- Loan Last Updated
Additionally, users can now pass in an orderBy parameter to order the results by an individual timestamp.
- If a single timestamp is requested and no orderBy field is specified, orderBy will default to the timestamp passed in
- If multiple timestamps are requested and no orderBy field is specified, or if no timestamp and no orderBy field is passed in, orderBy will apply the route's default timestamp.
See the API Reference Documentation for available event timestamps that can be applied to each route.
Supporting the new URLA
- Integrators currently do not have a good way of determining whether an application is new or old URLA and what specific versions are being exported in the file-export API routes.
- In response, we added file export links to GET /home-lending/applications and GET /home-lending/applications/:id and added file export links to export-related BONS events
- POST /documents has changed it's request from "multipart/related" to "multipart/form-data"
Additional application fields
Added the following fields to the request bodies for both POST and PATCH /home-lending/applications:
Added the following fields to the request body for PATCH/home-lending/applications:
Additional parties fields
Added the following fields to the request body for PATCH/parties/
Miscellaneous fields added
** "applicationRejected" added to the "integrationEvent.type" field
- GET/follow-ups, GET /follow-ups/:id, POST/follow-ups
** "requestedBy" field added to the response
- POST /lenders, GET /lenders
** "creditInternalAccountIdentifiers" added. Credit Internal Account Identifiers can now be tagged to the lender's profile upon creation
- PATCH /lenders
** Added ability to update existing credit internal account identifier associated with the lender. If the provided internal account identifier does not exist then a new entry will be created and attached to the lender's profile. The API does not support the deletion of existing credit internal account identifiers at this time.
Net new routes
- Tax Transcripts - retrieve structured tax transcript data for a particular 4506-T document
- PAB Activities - includes fields around PAB actions, granular credit pull and DU information, type of user (system/lender/borrower) and the specific user completing the actions.
Additional reports and fields around user information
We’ve added several additional fields to reports listed below, many of which enable you to easily identify the specific user/type of user completing actions.
Additional fields added to the following reports:
- Documents - type of user uploading the document (external API/internal API/borrower/lender)
- Loans - along with the additional fields from Loan Pipeline and Loan Statistics reports, we’ve also added a field containing a JSON array with details for all current assignees (user id, name, email), as well as a timestamp for when a Pre-approval Letter was generated.
- Follow Ups - now contains a loan type field that can be passed in as a query parameter.
Streamlined field names
Timestamps have been updated to the naming convention of event name + “datetime” for consistency across reports.
What You Need to Do to Upgrade to v3 or above
v2.0.0-v2.3.0 of Blend's APIs and Events will be fully deprecated (turned off) on April 30, 2021. Customers and Partners need to upgrade any API calls they are currently making and any webhooks they are processing to support v3.0.0 or above by April 30, 2021.
To upgrade to v3.0.0+:
Please see the upgrade guides for v3.0.0-v.3.3.0.
To upgrade to v4.0.0:
For the Reporting endpoint specifically, there are breaking changes occurring between v.2.x.x-v3.3.0 to v4.0.0. Please see the V4 Transition Guide for specific information on the changes.
For all endpoints outside of the Reporting endpoint, there are minor changes from v3.3.0 outlined above. If you are using a version lower than v3.3.0 currently (for non Reporting endpoints), please see the v3.3.0 Changelog for how to upgrade.
Updated almost 2 years ago