# Overview

For the complete and simple summary of the changes below see the[ v3.0.0 Changelog](🔗).

This document is an extension of the above Changelog that gives more context on these changes. It is for users of Blend's APIs to help you understand:

• Changes that impact the behavior of the API in this version

• What you will need to do to upgrade to v3.0.0 from v2.X.X

• New features and functionality that are available to you in v3.0.0

Don't forget that **v2.X.X functionality** will no longer be supported as of **October 31st, 2020.**

# Announcements

## Major Improvements in v3.0.0

**Intuitive** Consistent language used across all routes, and similarly structured routes behave in a similar and consistent way. 

**Extensible** The organization of data and routes makes it easier and obvious how to add support for new features or data sets.

**Best Practices** Utilize industry best practices from both REST and MISMO to drive ease-of-use and extensibility.

**Beyond Mortgage** Many of the changes made, including the largest reorganizations of route, were made with the idea of allowing Blend's APIs to be extended to handle use cases for many Banking Solutions beyond just Home Lending. 

# Breaking Changes

## New "Tenant Header" Format

Blend originally supported 2 separate headers to determine which tenant an API call was targeting:

• x-blend-deployment-header

• x-blend-special-instance-id

Both of these headers have been deprecated as of the v2.0.0 launch in November 2018.

They have been replaced by the combined header with the following format.

• blend-target-instance: [tenant]~[special instance id]

**All integrators need to plan to upgrade to utilizing the new header format, blend-target-instance, by the v3 depreciation deadline of October 2020. This change applies to ALL API routes.**

## Beyond Mortgage: Changes to Support a Multi-Banking-Solution Platform

As we expand how we serve our customers, Blend wants to make sure its features are extensible across not only the entire home lending life cycle, but also for other banking solutions like Deposit Account Applications, Auto Loans, Credit Cards, etc. 

In order to accomplish this Blend is updating one of its core resource names, "Loans" to "Applications", and adding the new concept of "Solution Types".

A Solution type is a category of group of products that a financial institution offers that share a similar application process, compliance standards and workflows, e.g. Deposit Accounts, Auto Loans, or Credit Cards. The introduction of the Solution concept will allow Blend's tools to be customized to provide the best integration and end-user experience for each unique banking solution, while also maintaining some core concepts – like applications, parties and documents – across all solutions. 

This will both make it easier for customer to integrate with Blend for multiple solutions, as well as make it easier for Blend to expand any features it builds for one banking vertical across the other solutions we support as well. 

• Addition of Solution Types

  • Solution specific routes are now prefixed with their solution name, e.g. all /loans routes and subroutes are now /home-lending/applications

  • loanType (originationType in Blend webhooks) → solutionSubType

  • permittedLoanType is now permittedSolutionSubType

• Loans → Applications

  • All /loans Routes are now /home-lending/applications

  • loanID is now applicationID

  • Array keys that were previously "loans" are now "applications"

## Consolidated Borrowers, Realtors and Third-Party Recipients (TPRs) into one set of Party Routes/Objects

As we've grown our support for parties other than just borrowers, we've found that they need support the same kind of data capture and features that we've already historically provided for borrowers. We also believe that the over-arching concept of a "party" that connects a Blend user (or potential future user) to an application as a participant will be a valuable concept as Blend expands many of our current features like disclosures beyond just home lending, as well as beyond our current set of supported parties within home lending. 

Therefore, we are starting the process of consolidating our treatment of Borrower parties, Realtors and Third-Party Recipients within our API. This means you'll see several changes in v3 and going forward: 

• The top-level Borrowers routes have been marked deprecated and that behavior has been merged in to the top-level Parties routes

• The top-level parties route and home-lending/applications parties sub-route now handle the retrieval, creation, updating and deletion of all types of parties 

• In other routes where a borrowers or thirdPartyRecipients object was previously returned, now a consolidated parties object will be returned which will include all of the types of parties associated with the application

• The schema previously exposed for borrower information has been brought in alignment with the more general parties schema, and borrower parties are now determined by "partyType" in the same way the type of Third-Party Recipients were differentiated before. 

Additionally, the borrowerEmail query parameter for GET /loans was changed to partyEmail and can now match on any party's email, not just borrowers.

## New Follow-ups Routes and Events Added

Integrators now have the ability to add follow-up processes to an application and assign them to parties on the application, as well as the ability to see all follow-ups currently or previously active on an application, and remove follow-ups from an application.

This includes any of the standard Blend follow-ups, custom follow-ups defined in the tenant's Blend instance configuration, and ad-hoc e-sign templates that utilize Blend's native Docusign integration to power e-signature for a variety of use cases in the post-submission application life cycle, including appraisal and home inspection.

To complete this integration flow, Blend now also offers UPDATE event notifications so integrators can know when a follow-up has been completed, declined or removed.

## Event Webhook schemas standardized on a "CRUD Notification" or "Special Trigger" pattern

All webhooks have been standardized on one of two schemas:

• CRUD Notification Schema

• Special Trigger Schema

The primary schema that most events use is the "CRUD Notification" pattern. This pattern indicates the top-level resource that was changed, if the change was a Creation, Update or Deletion, and if if it was an Update, what fields were changed. It does not include the values of the fields that were changed. Instead, all events include a "Links" section that includes the relevant API queries to grab the information needed to run a diff between two systems. 

This change will make it faster and easier for Blend to add new events, and more information to existing events. Additionally, it will help us more easily support webhook events for Custom Fields in the future. Please, note that although Blend has moved to a schema that support a "CRUD Notification" pattern, we do no yet support CRUD Notifications for all fields or Top-level resources.

Any events that do not fit into the standard "CRUD Notification" pattern will use the "Special Trigger" pattern. For example, TRID events will now utilize this pattern. This pattern is very similar to the the "CRUD Notification" schema, in that it will include the top-level resource that was changed and Links to the relevant API queries. However, these events include more specialized and flexible information relevant to the specific trigger that occurred, instead of just what information was updated. 

## Assignment Behavior made consistent across /loans routes

The referrerEmail field in POST loans had previously been used to set the initial assignee on the loan. This field will be removed from this route. The existing PUT/PATCH assignees routes will replace this behavior. 

The GET loans routes previously returned the “Primary Assignee” via loanOriginator field. This field will be replaced by the same assignees object returned by the assignees routes. 

## Improvements to Document Routes Behavior

"/v1/" has been removed from document download URL links

When downloaded via a v3 route or above, Documents will no longer be automatically marked as exported. To mark a document as exported, customers will call the PATCH document/id route for that document and set it's export-status to exported.

The includeAllExports query parameter and losExportedAt fields have been removed from the GET /documents routes. This behavior has been replaced by the GET /documents/id/export-statuses route and query parameters.

A lastExportedAt field has been added to the GET /documents routes. This field show the last time the document was exported by ANY person or system via the Blend's API or UI. 

Added GET /documents/id/export-statuses route. This route returns an array of any existing export objects for the specified document. Export objects include the timestamp when the export occurred, and an id of the system that triggered the export. This route can be filtered by the following query parameters: 

• exportedTo: allows exports to be filtered down to just a specific export location (like the LOS)

• exportedBefore and exportedAfter: allows the exports to be filtered by timestamp

The POST /documents route now no longer requires a content-type header. 

POST /documents now allows the sharing setting of the document to be determined when uploaded by the API similar to what can be done in the UI. This is determined by the `shareWithAllParties` body parameter when uploading a document.

`shareWithAllParties` defaults to "false" meaning the document will NOT be visible to associated parties by default. It can be shared with those parties by setting this parameter to "true" when POSTing a document.

## Loan File Export moved to its own Route

GET /loans/id is now GET /home lending/applications/id. GET /home lending/applications/id will now only return the standard JSON body response. The mortgage and home equity file export behaviors will be moved to GET /home lending/applications/id/file-export.

This brings the /loans/id route fully in line with the GET /loans List route and simplifies the route's behavior. It separates out the behavior required only for loan file exports and allows this behavior to be more easily extended without affecting the core GET loans/id behavior. We believe this will be very important during the FNMA to MISMO 3.4 transition the industry will be tackling over the course of 2020 - 2021.

### Query Parameters Changes

**format:** possible values of "fannie" or "mismo"

• If "fannie" is passed as the format param, Blend will either return the Fannie 3.2 file (if applicable) or return an error if the underlying loan was created in the new URLA format (MISMO 3.4).

• If "mismo" is passed as the format param, Blend will return the MISMO 3.3.1 file for loans in the current format or the MISMO 3.4 file for loans created in the new URLA format.

### Encoding Changes

This endpoint will return the relevant files in UTF-8 encoding.

### Support for the New URLA

With the anticipated new URLA changes, you will also be able to retrieve the MISMO 3.4 file using this endpoint. The MISMO 3.4 file will only be returned if the loan was created in the new URLA format.

As of 10/31/19, new URLA is only available to test in Blend BETA environments.

We will support new URLA loans in PROD once we have finalized GSE timelines for the new optional and mandatory use periods.

## Current Disclosures Routes Deprecated and Removed from v3.0.0

The Disclosures functionality is undergoing significant improvements that will be launched as part of the v3.1.0 API release at the end of January 2020.

To avoid any interim confusion for customers upgrading to v3 or above functionality, the disclosures routes currently available in v2.3.0 and below have been removed from v3.0.0.

Any customers or partners integrating with Blend's disclosures functionality between October 2019 and January 2020 should utilize the v2.3.0 Disclosures routes, and plan to upgrade to the newly exposed disclosures functionality between January 2020 and the v2 depreciation deadline in October 2020.

## Property Data Consolidated into a Consistent Object

The following fields in the /loans routes have been consolidated from top level fields/objects into a property object: 

• propertyAddress Object

• propertyType field

• propertyUsageType field

• propertyValue field

• propertySearchType field

## SSN transitioned into a more Flexible Object to Support Internationalization

The SSN or SocialSecurityNumber field has been transitioned into an object as outlined by the MISMO data dictionary. 

The object is called taxpayerIdentifier and returns a value and a type field. 

This change sets Blend and our integrators up to support international borrowers in 2020. 

## Phone Numbers fields are now objects and are Consistently Typed as Strings

Blend only accepts 1 phone number for most kind of users in our system. However, phone number fields like homePhone and workPhone have been consistently replaced by a phone numbers array of phone number objects. The phone number object includes a value field and a type field. This allows us to more easily expose different types of phone numbers for different parties, indicate what kind of phone number a specific value is, and easily move to support multiple phone numbers for parties in the future. 

Additionally, phone numbers were previously typed differently in different routes – sometimes as a number and sometimes as a string. As part of this standardization on a phone number object, phone number values have now been standardized and all Phone Numbers are typed as strings across all routes. 

## Names (e.g. Borrower Name) now always returned as Objects, never Strings

Blend APIs and webhooks will now use the expanded Name Object everywhere that the Name string field was previously used. 

## Several Field and Route Names Improved for Clarity

• applicationType is now applicationExperienceType

  • Blend specific field that determines what kind of end-user experience will be provided to the consumer. This update helps differentiate this from other kinds of application types like HELOC, Refinance or Auto Loans.

• GET /current-user is now GET /authentication-status

  • Allows you to check if your API user credentials authenticate before moving forward with a set of API actions. This change clarifies it’s purpose. 

• GET/PUT loan/id/application-details are now GET/PUT home-lending/applications/id/borrower-positions

  • Allows borrowers to be moved around on and between 1003 files. This changes clarifies it’s purpose.

## "default" Version Header Behavior Changed

The "default" version of the API will now be pointed at the most recently released stable version. If a customer is passing a version header of "default" this will result in an "automatic" version upgrade whenever a new version is released. 

Passing experimental as the version header will still result in being pointed to the next-up unreleased version of the API. There is no change in behavior for this header. 

As always, Blend recommends setting a specific version number as the header for all calls. 

## Consistent Timestamps: UTC Time in ISO format

As part of our v2 release we intended to standardize all timestamps on the the ISO format, but we missed a couple places. In particular, our webhook events will now be using the ISO timestamp format to align with the timestamps returned by the API. 

## All List GET routes now return Keyed Arrays

All routes that can return an array of results now return keyed (a.k.a. named) arrays. This changes handles a minor security vulnerability that can be exploited in certain Windows environments, and future-proofs against any future vulnerabilities. 

## List GET routes and Individual GET routes now return the same schemas

All List routes will return the same schemas as the Individual routes, and vice versa. Any new data added to one will be added to the other automatically.

## All GET routes now return all relevant fields from the corresponding POST route

Any field that can be set in a POST route will now be returned by GET routes as well. 

# What You Need to Do to Upgrade to v3 or above

## Getting Started with your Upgrade

v2.0.0-v2.3.0 of Blend's APIs and Events will be fully deprecated (turned off) on October 31st, 2020. 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 October 31st, 2020. 

The below table will help integrators identify which changes affect the routes and events they rely on. However, the Blend API Reference on Blend's Developer Docs should be referred to as the final source of truth for the structure and schemas of the APIs when upgrading. 

## API Changes Summary

NOTE: The change to the behavior of sending "default" as the API version header applies to ALL Blend Public API routes and is not specifically called out below

## Events Changes Summary