Disclosures Delivery and eSignatures
NOTE: Packages APIs currently require enablement from Blend Support. Package APIs are applicable to API versions 3.3.0 and above. Please email [email protected] for assistance.
Blend provides lenders the ability to post Disclosure packages for consumer(s) to view and sign. The package types can include any loan estimates, initial or closing Disclosures, and other Disclosure document packages that the consumer will need to view and/or sign in Blend’s disclosures experience.
This guide is meant for gathering all the proper information to post a proper disclosures package. However, in order to post a disclosures package into Blend, there are a few steps to take prior to ensure the packages are assigned to the correct recipients. Please refer to the Blend API Reference Guide for more in-depth documentation on individual API endpoints to get started with building against Blend’s APIs.
Authorization
For your app or your requests to be approved for access, you will need to authorize your application. Your app can be authorized for Blend’s API through issued credentials. Please contact [email protected] in order to obtain the necessary credentials.
Inputs required for posting a new disclosures package
Disclosures packages have a few inputs that are required in order to allow for Blend to know how to issue properly. These inputs, as well as how to retrieve them, are as follows.
Recipients
Disclosures packages need to be assigned to individual recipients. You will need to find the individual recipients that exist on the application in order to issue. The application ID is just the ID of individual application for which you are trying to issue the disclosures package. The party IDs can be found on the id fields under the party objects.
GET /home-lending/applications/:applicationID
{
id: string,
assignees: [
{
userId: string,
role: "PRIMARY_ASSIGNEE"
}
],
parties: [
{
id: string, // THIS IS BORROWER PARTY ID
applicationId: string,
email: string,
type: "BORROWER",
name: {
firstName: string,
lastName: string
},
status: string,
econsent: {
status: string,
ip: string,
date: string
},
phoneNumbers: [
{
phoneNumber: string,
type: string
}
]
},
{
id: string, // THIS IS COBORROWER PARTY ID
applicationId: string,
email: string,
type: "COBORROWER",
name: {
firstName: string,
lastName: string
},
status: string,
econsent: {
status: string
},
phoneNumbers: []
}
],
referenceNumber: string,
status: string,
applicationStatus: string,
solutionSubType: string,
loanPurposeType: string,
applicationTemplateId: string,
loanAmount: number,
archivedStatus: boolean,
property: {
address: {
state: string
},
type: string,
usageType: string,
value: number,
searchType: string,
},
applicationExperienceType: string
}
Recipient E-Consent
If consumer eConsent status needs to be ensured before issuing disclosures packages, it is recommended to check that status immediately before sending documents or document packages to Blend in order to retrieve the most updated status.
This call will respond with a JSON representation of the application object. The eConsent status of the consumers can be obtained at the following path.
GET home-lending/applications/:id
{
_id: string,
application: {
borrowers: [
{
_id: string,
eConsentGiven: {
status: true,
}
},
]
}
}
Tabs
The following DocuSign tab types are supported for all package recipients and expose a subset of the fields for configuration via the API. The exposed fields and sample inputs are documented below.
approveTabs: [{
height: 0,
width: 0,
buttonText: "string",
xPosition: 0,
yPosition: 0,
pageNumber: 0,
tabLabel: "string",
name: "string"
}],
signHereTabs: [{
xPosition: 0,
yPosition: 0,
pageNumber: 0,
tabLabel: "string",
name: "string",
scaleValue: 1,
optional: false
}],
dateSignedTabs: [{
xPosition: 0,
yPosition: 0,
pageNumber: 0,
tabLabel: "string",
name: "string"
}],
checkboxTabs: [{
xPosition: 0,
yPosition: 0,
pageNumber: 0,
tabLabel: "string",
name: "string",
selected: true
}],
textTabs: [{
height: 0,
width: 0,
maxLength: 0,
required: false,
fontSize: "string",
xPosition: 0,
yPosition: 0,
pageNumber: 0,
tabLabel: "string",
name: "string"
}],
radioGroupTabs: [{
xPosition: 0,
yPosition: 0,
pageNumber: 0,
tabLabel: "string",
name: "string",
groupName: "string",
radios: [
{
tabId: "string",
xPosition: 0,
yPosition: 0,
pageNumber: 1,
value: "string",
selected: true,
required: false
}
]
}]
Additional reference materials and the full list of valid input values per field can be found in Docusign’s API guides below.
Tab Extraction from Embedded Fields
Blend can extract DocuSign tabs from documents that have certain types of embedded fields. This means that, if you have the right kind of documents, you can have Blend extract the tabs from the documents themselves instead of specifying the tabs yourself in the disclosures package POST request. If you are not sure if your documents have embedded fields or what type of embedded fields they have, contact [email protected] to find out if your Blend supports tab extraction for your document type(s). Currently, Blend supports tab extraction for documents from Wolters Kluwer's Expere and Ellie Mae's Encompass. In order to leverage Blend's tab extraction, include the following in your POST Package request, in the corresponding document object:
// in POST Package payload
// in envelopes -> recipients -> metadata -> documents
// see section "Posting a new disclosures package" for more info
tabs: [],
tabExtractionMethod: "EXPERE_ACROFORM",
extractTabs: [
{
fieldName: string, // name of the AcroField from Expere
required: boolean // optional, defaults to true
}
]
// in POST Package payload
// in envelopes -> recipients -> metadata -> documents
// see section "Posting a new disclosures package" for more info
tabs: [],
tabExtractionMethod: "ENCOMPASS"
Posting documents relevant to the package
Disclosures packages in Blend are a collection of documents meant for further action to be taken by various recipients. Therefore, in order for the package to be issued to the recipients defined above, the set of required documents meant for further action will need to be posted. Documents are posted as follows:
//POST /documents
{
body: {
metadata: {
shareWithAllParties: boolean,
applicationId: string,
losType: string,
losTypeId: string,
name: string,
status: string,
type: string,
partyIds: [], // list of parties on the loan that you want to be associated with this document
},
data: Buffer.toString(), // stringified buffer with content type application/pdf
}
}
{
id: string, // URL
applicationId: string,
created: string,
downloadUrl: string, // URL of uploaded document
}
More information and an example can be found in the documents API documentation: https://developers.blend.com/blend/reference#post-document
For the purposes of this guide, the piece of the response that is needed for disclosures package creation is the id field. These are each of the document ID that will need to be associated with the disclosures packages, each of which refer to the corresponding documents that have been posted into Blend.
Posting a new disclosures package
Now that all of the necessary information has been obtained, the request can be easily constructed. The response is going to a JSON object containing a ID with a GUID value, which is the ID of the new package that has just been created.
A sample request has been constructed below, as an example, along with a sample response. Full API documentation for this endpoint can be found here: https://developers.blend.com/blend/v3.3.0/reference#post-a-disclosures-packages
{
"type": "OTHER_DISCLOSURE",
"name": "Multi-tiered 24 hour productivity",
"description": "This is a partnerships package to push for infomediaries. De-engineered 24 hour service-desk",
"foreignPackageId": "123",
"applicationId": "4ec7c0d9-22b9-4d6e-8358-b00d6f296437",
"envelopes": [
{
"providerType": "WETSIGN",
"recipients": [
{
"partyId": "5bcb0715-c7c8-4345-931d-ea076029bf36",
"metadata": {
"documentIds": [
"64fa61de-9d12-4d17-b432-bbd928091356"
]
}
},
{
"partyId": "ff533603-833e-4dca-af10-e4a37269f7d2",
"metadata": {
"documentIds": [
"64fa61de-9d12-4d17-b432-bbd928091356"
]
}
}
]
},
{
"providerType": "ESIGN",
"recipients": [
{
"partyId": "5bcb0715-c7c8-4345-931d-ea076029bf36",
"metadata": {
"documents": [
{
"documentId": "c6efecac-c29e-401e-82b1-1fb5b7c009d6",
"tabs": [
{
"type": "signHere",
"attributes": {
"xPosition": "50",
"yPosition": "590",
"pageNumber": "1"
}
},
{
"type": "dateSigned",
"attributes": {
"xPosition": "240",
"yPosition": "629",
"pageNumber": "1"
}
}
]
},
{
"documentId": "48053270-4354-42b8-94f2-d7a2c639d731",
"tabs": [
{
"type": "signHere",
"attributes": {
"xPosition": "40",
"yPosition": "90",
"pageNumber": "1"
}
},
{
"type": "signHere",
"attributes": {
"xPosition": "50",
"yPosition": "400",
"pageNumber": "4"
}
},
{
"type": "signHere",
"attributes": {
"xPosition": "50",
"yPosition": "670",
"pageNumber": "6"
}
},
{
"type": "dateSigned",
"attributes": {
"xPosition": "250",
"yPosition": "440",
"pageNumber": "4"
}
},
{
"type": "dateSigned",
"attributes": {
"xPosition": "240",
"yPosition": "710",
"pageNumber": "6"
}
}
]
}
{
"documentId": "c6efecac-c29e-401e-82b1-1fb5b7c009d6",
"tabs": [],
"tabExtractionMethod": "EXPERE_ACROFORM",
"extractTabs": [
{
"fieldName": "SIG_Borrower_1_C1000123456_true_1"
}
]
}
]
}
}
]
}
]
}
{
"_id": "8b600021-e36d-471e-b769-12c99c131598" // the package ID
}
Request fields descriptions:
typeis the type of disclosures package. The options here are:OTHER_DISCLOSURE,INITIAL_LOAN_ESTIMATE,REVISED_LOAN_ESTIMATE,CLOSING_DISCLOSURE,REVISED_CLOSING_DISCLOSUREnameis the name of the disclosures package. It is usually there for a package of typeOTHER_DISCLOSUREdescriptionis a string that describes what the package doesforeignPackageIdis a ID that is used by foreign systems to refer to the disclosures package.applicationIdis the ID of the Blend loan application that this disclosures package belongs toenvelopesare a representation of documents within Blend, split up by the necessary actions that need to be taken on them by the recipients. For example, there are e-sign envelopes and wetsign envelopes. E-sign envelopes contain documents that need to be electronically viewed and signed, while wetsign envelopes are documents that need to be physically signed and re-uploaded.providerTypeis the classification of the envelope based on the kind of documents it holds. The options here areESIGNandWETSIGN, the differences of which are addressed above.recipientsare the individuals who need to receive the documents in this specific envelope, NOT all of the recipients on the package.partyIdis the ID of the recipient party. A list of recipients, as mentioned earlier in the guide, can be found through theGET /home-lending/applications/:applicationIDendpoint.metadatais the metadata for each of the documentsdocumentIdsis a metadata field specific to theWETSIGNenvelope. These are the document IDs for the documents that need to be associated with this disclosures package. The IDs are obtained by posting the documents into Blend and then receiving the autogenerated Blend IDs from the response of thePOST /documentscall.documentsis a metadata field specific to theESIGNenvelope. This holds a list of documents, each with a document ID and a list of tabs for possible actions by the signees.documentIdis the document ID for documents that need to be associated with this disclosures package. The IDs are obtained by posting the documents into Blend and then receiving the autogenerated Blend IDs from the response of thePOST /documentscall.tabsare a set of coordinates, as described earlier, meant to dictate locations on each document where certain actions are to be taken by recipients.
Request fields descriptions:
_idis the Blend autogenerated GUID that points to the package that was just posted with the corresponding request.
Getting event updates
After successfully posting a disclosures package, you should be able to register your application to get events for these disclosures packages.
More about our event notification system and requesting access for receiving events from it can be found here: https://developers.blend.com/blend/docs/getting-started
Example events for disclosures packages updates can be found here:
https://developers.blend.com/blend/v3.3.0/docs/package-events
Checking package status
The status and other metadata of a particular disclosures package can be retrieved through APIs.
If you know the disclosures package ID:
GET /packages/:disclosuresPackageID
{
id: string,
applicationId: string,
status: PackageStatus,
paperedAt?: string,
envelopes: {
id: string,
providerId: string,
signatureRequired: boolean,
status: 'HAS_NOT_VIEWED' | 'VIEWED' | 'SIGNED' | 'COMPLETED' | 'DECLINED',
recipients: [{
partyId: string
partyType: 'BORROWER' | 'LENDER' | 'SETTLOR' | 'SPOUSE' | 'TITLE_HOLDER' | 'OTHER',
status?: 'HAS_NOT_VIEWED' | 'VIEWED' | 'SIGNED' | 'DECLINED'
metadata: {} // Metadata varies based on the type of Envelope
}]
},
type: 'OTHER' | 'INITIAL_LOAN_ESTIMATE' | 'REVISED_LOAN_ESTIMATE' | 'CLOSING_DISCLOSURE' | 'REVISED_CLOSING_DISCLOSURE',
name?: string,
description?: string,
foreignPackageId?: string,
}
However, if you do not have the disclosures package ID, you will be able to pull multiple disclosures packages based on a specific application (along with other params).
Application Query:
//GET /packages
query: {
applicationId: string // REQUIRED: searches by loan ID
foreignPackageId?: string // OPTIONAL: package ID from creation party
status?: 'CREATED' | 'DELIVERED' | 'VIEWED' | 'SIGNED' | 'COMPLETED' | 'DECLINED' | 'FAILED_TO_CREATE' | 'CANCELLED' | 'RETRIEVED' // OPTIONAL: search for all packages with a certain status
}
[...disclosures] // an array of disclosures, where each individual disclosure is the same as the package ID response.
Marking packages as papered out
When disclosures packages are papered out rather than electronically delivered, marking them as such is supported.
//PATCH /packages/:disclosuresPackageID
{
body: {
paperedAt: string // this should be an isodate timestamp. e.g. 2011-10-05T14:48:00.000Z
}
}
200 OK
Cancelling packages
Cancelling existing disclosures packages through the API is supported.
//PATCH /packages/:disclosuresPackageID
{
body: {
status: 'CANCELLED'
}
}
200 OK
Updated almost 2 years ago