HomeGuidesAPI ReferenceChangelogDiscussions
GuidesAPI ReferenceDiscussions

Closing a Loan Electronically

How to use the Blend Close APIs to list, query, create, update, and submit closings.

This guide will walk you through listing, querying, creating, updating, and submitting closings in Blend using Blend's Public API.

Prerequisites

A closing is attached to an application thus the first piece of information you'll need to be able to either look up all closings attached to an application or create a new closing is an application ID.

You'll also need to provide the headers required by all Blend APIs. Please refer to the Quick Start Guide for more information.

Listing Existing Closings for an Application

You can query the list of closings currently attached to a particular application by making a GET request to the close/closings endpoint, such as:

curl 'https://api.beta.blendlabs.com/close/closings?applicationId=<uuid>' \
-H '[Required Blend Headers - See the Quick Start Guide: https://developers.blend.com/blend/docs]'

This endpoint returns a list of closings in JSON format. The list can be empty, like [], or it can contain one or more closings, like this:

[
  {
    "id": "b2006a70-a19b-4b7f-973d-3a561e159060",
    "createdAt": "2019-10-29T04:25:30.000Z",
    "applicationId": "aa9fdaa2-7bf3-4411-a836-c2a46117f5c3",
    "closingType": "RON",
    "titleAgent": {
      "id": "5c86aa6b-f428-48f6-ac64-bbc0c0878453",
      "createdAt": "2019-10-29T04:25:30.000Z",
      "email": "[email protected]",
      "firstName": "John",
      "lastName": "Hernandez",
      "titleAgency": {
        "id": "301e0c97-58b3-4c4c-a804-59bfb53b71b3",
        "createdAt": "2019-10-29T04:25:30.000Z",
        "name": "Title Co."
      }
    },
    "closingStart": "2019-10-29T04:25:30.000Z",
    "closingEnd": "2019-10-30T04:25:30.000Z",
    "documentReferences": [
      {
        "id": "e28581e6-53c8-4ad0-b171-6418a9795539",
        "createdAt": "2019-10-29T04:25:30.000Z",
        "documentID": "ce9e2ba8-d228-4a6a-949c-4da7a7434844",
        "sourceType": "LENDER",
        "closingDesignation": "NOTE"
      }
    ],
    "closingStatus": "COMPLETED"
  }
]

See the next section for details about the fields returned in each closing.

Getting Information About a Closing

We've seen how to list all closings for an application, which is great when you only have the application ID, but once you already know the ID of a closing, you can query it directly using the GET /close/closings/:id endpoint as follows:

curl 'https://api.beta.blendlabs.com/close/closings/<closing_id>' \
-H '[Required Blend Headers - See the Quick Start Guide: https://developers.blend.com/blend/docs]' \

The JSON response is the same as a single element of the array returned by the GET /close/closings endpoint and includes all the information available about a closing:

{
  "id": "b2006a70-a19b-4b7f-973d-3a561e159060",
  "createdAt": "2019-10-29T04:25:30.000Z",
  "applicationId": "aa9fdaa2-7bf3-4411-a836-c2a46117f5c3",
  "closingType": "RON",
  "titleAgent": {
    "id": "5c86aa6b-f428-48f6-ac64-bbc0c0878453",
    "createdAt": "2019-10-29T04:25:30.000Z",
    "email": "[email protected]",
    "firstName": "John",
    "lastName": "Hernandez",
    "titleAgency": {
      "id": "301e0c97-58b3-4c4c-a804-59bfb53b71b3",
      "createdAt": "2019-10-29T04:25:30.000Z",
      "name": "Title Co."
    }
  },
  "closingStart": "2019-10-29T04:25:30.000Z",
  "closingEnd": "2019-10-30T04:25:30.000Z",
  "documentReferences": [
    {
      "id": "e28581e6-53c8-4ad0-b171-6418a9795539",
      "createdAt": "2019-10-29T04:25:30.000Z",
      "documentID": "ce9e2ba8-d228-4a6a-949c-4da7a7434844",
      "sourceType": "LENDER",
      "closingDesignation": "NOTE"
    }
  ],
  "closingStatus": "COMPLETED"
}

Here is a description of each field:

  • id is the closing's unique identifier. It's what you'll need to update or submit the closing.
  • createdAt is a timestamp indicating when the closing was created.
  • applicationId is the UUID of the application this closing is attached to.
  • closingType is the type of closing. The possible values are:
    • RON: Remote Online Notarization.
    • HYBRID: In-person notarization with e-signing of documents that don't require notarization ahead of the closing day.
    • TRADITIONAL: In-person signing and notarization of all documents.
    • UNDETERMINED: Placeholder when the closing type is still unknown.
  • titleAgent is an object containing the following information about the title agent:
    • id is the agent's unique identifier with respect to the Blend Close API.
    • createdAt is a timestamp indicating when the record for this agent was created.
    • email is the email address of the agent.
    • firstName is the first name of the agent.
    • lastName is the last name of the agent.
    • titleAgency is an object containing the following information about the agent's title agency:
      • id is the agency's unique identifier with respect to the Blend Close API.
      • createdAt is a timestamp indicating when the record for this agency was created.
      • name is the name of the title agency.
  • closingStart is the timestamp of the start of the closing period.
  • closingEnd is the timestamp of the end of the closing period.
  • documentReferences is an array containing the following information about each closing document:
    • id is the closing document's unique identifier with respect to the Blend Close API. Not to be confused with the documentID below.
    • createdAt is a timestamp indicating when the record for this document was created.
    • documentID is the ID of the document with respect to the Blend Documents API (Reference).
    • sourceType is the type of source for the document. The possible values are:
      • LENDER: The document was originated by the Lender.
      • TITLE: The document was originated by the Title Agency.
    • closingDesignation: The document's closing designation. The possible values are:
      • SIGN_AHEAD: The document doesn't require notarization and can be e-signed ahead of the closing date.
      • DAY_OF: The document must be signed on the closing date. It might or might not require notarization.
      • NOTE: eNote.
  • closingStatus: The status of the closing. The possible values are:
    • DRAFT: The closing is a draft and hasn't been sent.
    • SENT: The closing has been sent.
    • COMPLETED: The closing is completed.

Note that some fields are optional and might be omitted. For the complete list of optional fields, see the Blend Close API Reference.

Creating a Closing

To create a new closing for a given application, make a POST request to the close/closings endpoint, such as:

curl -X POST 'https://api.beta.blendlabs.com/close/closings' \
-H '[Required Blend Headers - See the Quick Start Guide: https://developers.blend.com/blend/docs]' \
-H 'Content-Type: application/json' \
--data-raw '{"applicationId": "<uuid>"}'

This creates an empty closing and returns its ID.

{
  "id": "<closing_id>"
}

Take note of that ID as you'll need it to update or query that closing later on.

Updating a Closing

The main way to update a closing is through the PATCH /close/closings/:id endpoint. This versatile endpoint lets you update most editable fields of a closing, either independently or all at once. The only exception is documents which are updated using the dedicated PUT /close/closings/:id/documents and DELETE /close/closings/:id/documents endpoints.

Patching a Closing

Let's look at examples for updating each piece of information separately, then we'll look at an example where we update multiple pieces of information at once. In any case, if the call succeeds, you'll get a 200 response.

Title Information

The PATCH /close/closings/:id endpoint can be used to set or update information about the Title Agent. The only required field is the agent's email.

curl -X PATCH 'https://api.beta.blendlabs.com/close/closings/<closing_id>' \
-H '[Required Blend Headers - See the Quick Start Guide: https://developers.blend.com/blend/docs]' \
-H 'Content-Type: application/json' \
--data-raw '{
  "titleAgent": {
    "email": "[email protected]",
    "firstName": "John",
    "lastName": "Hernandez",
    "agencyName": "Title Co."
  }
}'

Closing Type

The PATCH /close/closings/:id endpoint can be used to set or update the closing type. The possible values are:

  • RON: Remote Online Notarization.
  • HYBRID: In-person notarization with e-signing of documents that don't require notarization ahead of the closing day.
  • TRADITIONAL: In-person signing and notarization of all documents.
  • UNDETERMINED: Placeholder when the closing type is still unknown.
curl -X PATCH 'https://api.beta.blendlabs.com/close/closings/<closing_id>' \
-H '[Required Blend Headers - See the Quick Start Guide: https://developers.blend.com/blend/docs]' \
-H 'Content-Type: application/json' \
--data-raw '{"closingType": "RON"}'

Closing Date

The PATCH /close/closings/:id endpoint can be used to set or update the closing date. There are two ways to provide a closing date. The first one is by submitting a single date, the date of the closing, as an ISO timestamp. In this case, the closing date will be transformed into a 24h closing period starting at the beginning and ending at the end of the provided closing date:

curl -X PATCH 'https://api.beta.blendlabs.com/close/closings/<closing_id>' \
-H '[Required Blend Headers - See the Quick Start Guide: https://developers.blend.com/blend/docs]' \
-H 'Content-Type: application/json' \
--data-raw '{"closingDate": "2020-03-16T12:00:00-04:00"}'

The second way is by providing an actual period of closing defined as start and end date and times:

curl -X PATCH 'https://api.beta.blendlabs.com/close/closings/<closing_id>' \
-H '[Required Blend Headers - See the Quick Start Guide: https://developers.blend.com/blend/docs]' \
-H 'Content-Type: application/json' \
--data-raw '{
  "closingStart": "2020-03-16T00:00:00-04:00",
  "closingEnd": "2020-03-17T00:00:00-04:00"
}'

Note that you can't update closingDate and closingStart/closingEnd at the same time. Pick one method.

All at once

The PATCH /close/closings/:id endpoint can also be used to update any combination of editable fields all at once, for instance:

curl -X PATCH 'https://api.beta.blendlabs.com/close/closings/<closing_id>' \
-H '[Required Blend Headers - See the Quick Start Guide: https://developers.blend.com/blend/docs]' \
-H 'Content-Type: application/json' \
--data-raw '{
  "closingType": "RON",
  "closingStart": "2020-03-16T00:00:00-04:00",
  "closingEnd": "2020-03-17T00:00:00-04:00",
  "titleAgent": {
    "email": "[email protected]",
    "firstName": "John",
    "lastName": "Hernandez",
    "agencyName": "Title Co."
  }
}'

Updating Documents

Uploading Closing Documents

Uploading closing documents is a two-step process. You first have to use the Documents API to upload the documents into Blend and obtain their Blend Document IDs (id field in the response to POST /documents).

Note that some document types on an application will not be visible to borrowers (only visible to settlement agents) and therefore should not be added to a closing, such as CLOSING_SETTLEMENT_ONLY.

Then, you need to know the source type and the closing designation of the documents. The possible source types are:

  • LENDER: The document was originated by the Lender.
  • TITLE: The document was originated by the Title Agency.

The possible closing designations are:

  • SIGN_AHEAD: The document doesn't require notarization and can be e-signed ahead of the closing date.
  • DAY_OF: The document must be signed on the closing date. It might or might not require notarization.
  • NOTE: eNote.

For hybrid closings (HYBRID closing type), to enable e-signing of documents that have a LENDER source type and SIGN_AHEAD designation, one should specify recipients (recipients array whose items each contain a partyId) and how to obtain signing coordinates for each recipient. There are currently three tabs extraction methods (acceptable values for tabExtractionMethod) available:

  • EXPERE_ACROFORM: Extracts Expere Acroform embedded coordinates. Requires additional information in extractTabs. See below.
  • ENCOMPASS: Extracts Encompass embedded coordinates.
  • MANUAL: Requires manual tagging by Blend's Ops Desk. Should only be used for documents that don't contain embedded coordinates.

If recipients are not specified, by default all borrowers on the loan are added as recipients and the document is flagged for manual tagging (tabExtractionMethod is set to MANUAL).

To specify documents that do not need manual tagging but that should still be included in the package that gets reviewed by borrowers on the day of closing, i.e. view-only documents, you must specify recipients (party IDs) but omit the tabExtractionMethod.

In addition to partyId and tabExtractionMethods, each recipient can receive additional metadata, which might be required depending on the tab extraction method. For instance, with EXPERE_ACROFORM, one must specify the extractTabs array which contains additional information (most importantly fieldName) required to properly extract coordinates. One can also specify explicit tabs and omit tabExtractionMethod. This API is intentionally similar to the Packages API and is explained in more details in the Disclosures Delivery and eSignatures guide.

Note that the API also accepts an optional requireNotarization boolean property per document. While Blend does not currently use it, integrations should try to populate it if that information is available to them.

Finally, to attach the uploaded documents to the closing, you can use the PUT /close/closings/:id/documents endpoint as follows:

curl -X PUT 'https://api.beta.blendlabs.com/close/closings/<closing_id>/documents' \
-H '[Required Blend Headers - See the Quick Start Guide: https://developers.blend.com/blend/docs]' \
-H 'Content-Type: application/json' \
--data-raw '{
  "documents": [
    {
      "documentID": "<doc_uuid>",
      "sourceType": "LENDER",
      "closingDesignation": "SIGN_AHEAD",
      "recipients": [
        {
          "partyId": "<party1_uuid>",
          "tabExtractionMethod": "MANUAL"
        },
        {
          "partyId": "<party2_uuid>",
          "tabExtractionMethod": "MANUAL"
        }
      ]
    },
    {
      "documentID": "<doc2_uuid>",
      "sourceType": "LENDER",
      "closingDesignation": "DAY_OF"
    }
  ]
}'

If the call succeeds, you'll get a 200 response.

Updating Closing Documents Metadata

To update the closing designation (or source type) of a document, you just need to call the same PUT /close/closings/:id/documents endpoint and provide the existing document IDs along with the updated metadata:

curl -X PUT 'https://api.beta.blendlabs.com/close/closings/<closing_id>/documents' \
-H '[Required Blend Headers - See the Quick Start Guide: https://developers.blend.com/blend/docs]' \
-H 'Content-Type: application/json' \
--data-raw '{
  "documents": [
    {
      "documentID": "<existing_doc_uuid>",
      "sourceType": "LENDER",
      "closingDesignation": "DAY_OF"
    }
  ]
}'

Note that the metadata is fully replaced, not patched (PUT vs PATCH).

If the call succeeds, you'll get a 200 response.

Removing Closing Documents

To remove one or more documents from a closing, call the DELETE /close/closings/:id/documents endpoint and provide the list of comma-separated document IDs in the ids parameter:

curl -X DELETE 'https://api.beta.blendlabs.com/close/closings/<closing_id>/documents?ids=<doc_id1>,<doc_id2>' \
-H '[Required Blend Headers - See the Quick Start Guide: https://developers.blend.com/blend/docs]'

If the call succeeds, you'll get a 200 response.

Replacing Closing Documents

To replace a document, since the document ID is changing, you must make a call DELETE /close/closings/:id/documents to delete the previous version and PUT /close/closings/:id/documents to add the new one. The order in which you call them doesn't matter.

Note that the PUT /close/closings/:id/documents endpoint cannot be used to remove nor replace documents from a closing. This is to prevent accidental document removal when doing concurrent updates.

Creating an eNote

The POST /close/closings/:id/enote endpoint lets you create an eNote. The data required and how it's structured closely follows the contents of the eOriginal's seed XML. The first difference is that Blend accepts data as JSON rather than XML. The second difference is that some of the data gets pulled from Blend rather than being requested here.

For instance, the property address gets pulled directly from Blend. If it needs to be updated prior to generating the eNote, one should use the Home Lending - Application API to do so.

Similarly, the list of signers is deduced from the list of borrowers in Blend. These can be updated beforehand using the Borrowers API. Note that we don't support specifying power of attorney as of yet.

The original loan amount is also pulled from Blend but can be overridden by providing a value for originalLoanAmount when calling the endpoint.

Lastly the lenderLoanId field is also populated from Blend data if not provided.

To create the eNote, make a POST request to the /close/closings/:id/enote endpoint. For instance:

curl -X POST 'https://api.beta.blendlabs.com/close/closings/<closing_id>/enote' \
-H '[Required Blend Headers - See the Quick Start Guide: https://developers.blend.com/blend/docs]' \
-H 'Content-Type: application/json' \
--data-raw '{
  "smartDocTemplateData": {
    "fixedLoan": {
      "formId": "3200e",
      "scheduledFirstPaymentDate": "2018-03-14",
      "paymentRemittanceDay": 3,
      "lienPriorityType": "FirstLien",
      "noteRatePercent": 13.85,
      "loanMaturityDate": "2048-12-13",
      "originalPrincipalAndInterestPaymentAmount": 14460.45,
      "lateChargeGracePeriod": 8,
      "lateChargeRate": 13.45,
      "lateChargeMaximumAmount": 20.15,
      "conformingYearType": "Pre2010",
      "notePayToAddress": {
        "streetAddress": "1180 6th Avenue",
        "city": "New York",
        "state": "NY",
        "postalCode": "10036"
      },
      "closingDocumentInfo": {
        "executionDate": "2018-03-14",
        "executionCity": "New York",
        "executionState": "NY",
        "agent": {
          "unparsedName": "Nelson and Nelson",
          "type": "Attorney",
          "contactName": "Matthew Nelson",
          "postalAddress": {
            "streetAddress": "403 W 49th Street",
            "city": "New York",
            "state": "NY",
            "postalCode": "10019"
          }
        },
        "lender": {
          "unparsedName": "Northstar Lending",
          "contactName": "Harold Osborn",
          "nmlsId": 665444
        },
        "loanOriginator": {
          "unparsedName": "Northstar Lending",
          "nmlsId": 353553
        }
      }
    }
  }
}'

If the call succeeds, you'll get a 200 response.

Submitting a Closing

Finally, when the loan is clear to close, you can submit the closing using the POST /close/closings/:id/send endpoint. You must provide the source type (either LENDER or TITLE) in the body of the request:

curl -X POST 'https://api.beta.blendlabs.com/close/closings/<closing_id>/send' \
-H '[Required Blend Headers - See the Quick Start Guide: https://developers.blend.com/blend/docs]' \
-H 'Content-Type: application/json' \
--data-raw '{"sourceType": "LENDER"}'

Note that the call will fail and return a clear error message if the closing is missing information, like if the closing type is still UNDETERMINED or if no closing documents have been attached.

If the call succeeds, you'll get a 200 response.

Once submitted, the closingStatus will change from DRAFT to SENT and you won't be able to modify it further.