Disclosures Delivery and eSignatures

Developer Guide: Electronic Disclosures Delivery and eSignatures in Blend

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 the DocuSign experience.

Blend’s API for displaying documents within the portal and supporting consumer eSignature workflows comprises two main steps:

1. Posting the individual document to Blend’s APIs
2. Posting the document package to Blend’s APIs using the document UUIDs generated in the previous step

Please refer to the Blend API Reference Guide to get started with building against Blend’s APIs.

Step 1: Post document request

Use type: "other-disclosures" for any document that needs to be displayed to the consumer in Blend.

POST https://api.blendlabs.com/documents

    Content-Type: multipart/related; boundary=boundary_string
    --boundary_string
    Content-Type: application/json; charset=UTF-8
    {
      type: "other-disclosures",
      loanId: "",
      borrowerIds: [ "", ... ],
      name: "", // optional
      losType: "", // optional - Use to specify the consumer-facing document name
      losTypeId: "", // optional
    }
    --boundary_string
    Content-Type: application/pdf
    BASE64-ENCODED PDF_DATA_STREAM
    --boundary_string--

A successful response (200 OK) to the document post will contain metadata for the document. For each document being added to a package, the id value must be stored in the package post.

{
  id: "", // documentUUID
  type: "",
  loanId: "",
  name: "",
  downloadUrl: "",
  created: ISO Timestamp,
  borrowerIds: [""],
  losExportedAt: ISO Timestamp
}

Step 2: Post document package request

Creating the package of documents creates the necessary workflows in Blend for delivering the documents and eSign experience to the consumer. This post contains the requisite information to create and properly assign form fields, such as signature and checkbox tabs in DocuSign. This information is specified on a per-document basis. A package name and description can also be specified within the call; the name and description will appear in the consumer UI, indicating what documents the package contains.

POST https://api.blendlabs.com/disclosures-packages

{
  loanId: "",
  losId: "",
  type: "other",
  name: ""
  description: "",
  documents: [
    {
      id: "", // blend document id
      borrowers: [
        {
          id: "", // blend user id
          tabs: {DOCUSIGN TAB TYPES}
        }
      ],
      lender: {
        id: "", // blend user id
        tabs: {DOCUSIGN TAB TYPES}
      },
      isWetsign: false,
    }
  ]
}

A successful response (200 OK) to the document post will contain metadata for the document. For each document being added to a package, the id value must be stored in the package post.

Docusign Tab Types

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 Types
• Envelope Creation

📘

Package Creation versus Package issuance

Successful creation of a package does not necessarily mean that the package was issued to consumers.

Consumers must provide eConsent within Blend before having documents delivered to them electronically. Blend provides a configuration option to the customer, where the initial post of Disclosures packages can return an error if the consumer has not accepted eConsent at the time of the post.

Checking package status

Document package status can be queried at any time by querying for all packages on a particular loan and using the package ID returned when creating the package.

GET /disclosures-packages?loanId={loanId}


{
  disclosuresPackages: [
    {
      id: "",
      status: "",
      type: "",
      documents: ["", ...], // list of document ids in the package
    },
  ]
}

Checking Consumer eConsent status

If consumer eConsent status needs to be verified, it is recommended to call to the API for that status immediately before sending documents or document packages to Blend, in order to retrieve the most updated status.

GET /loans?loanId={loanId}

This call will respond with a JSON representation of the loan object. The eConsent status of the consumers can be obtained at the following path.

{
  _id: "",
  application: {
     borrowers: [   
      {
        _id: "",
        eConsentGiven: {
          status: true,
        }
      },
    ]
  }
}

Event notifications for document delivery and eSign in Blend

Blend is able to event notifications related to document delivery and eSign workflow to a customer listener service. The main events in this case are:

• Document available event - A document in a package is ready for export
  • This event is sent when the workflow is complete for the specified document
  • In the case of eSign, this means that the consumer has completed their actions in DocuSign for that package
  • This event contains information necessary to interact with the API in order to programmatically download the document
  • This event is sent on a per-document basis. In the case of a package of documents, when the package has been completed Blend will send an event for each document in the package in quick succession
  • Wet sign and upload
• Package viewed event - The package has been viewed by the consumer in DocuSign
  • This event is sent on a per-consumer basis. Identifying which consumer viewed the documents to trigger this event
• Disclosures signed event - Triggered for each consumer on the loan when they sign electronically
• Package status changed event - The package object’s status has changed

For the full list of Blend events, please visit https://developers.blend.com/docs/api/events/events-subscription