Last modified: 2022-09-23

REST API

OneSpan Sign has created a Digital Mortgage Solution that can store an e-Note from a mortgage transaction in a digital vault. For a given transaction, OneSpan Sign vaults a single e-Note in SMART Document format.

Certain REST API settings associated with a OneSpan Sign transaction can specify which document should be vaulted, and in which organization and vault it should be stored. After being vaulted, the original SMART document is deleted from OneSpan Sign's database.

eOriginal and OneSpan both provide vaults for e-Notes. The following sections describe how to use their vaults:

The Smart Document templates that OneSpan Sign uses for transactions involving mortgages support ARC sections within the template. This feature is required by the USA's Federal Home Loan Mortgage Corporation (also known as Freddie Mac).

Creating a transaction or template with the REST API always involves certain standard settings — see Signer Experience Settings.

If you want to view all existing calls, see our interactive Open API Specification. From there you can download the YAML file for our REST API, search for specific endpoints in that API, and even try a few calls yourself.

Whenever an attempt to eDeposit documents in an eOriginal vault fails, OneSpan Sign sends a notification to the Sender of the associated transaction via a Callback Event. Once the effort to vault a document suffers a non-recoverable error, OneSpan Sign sends the Sender an email about the failure. That email’s template cannot be customized.

Using an eOriginal Vault

If you want to store an e-Note in an eOriginal vault, the first thing you need to do is to ask our Support Team to enable this functionality for your account.

To instruct OneSpan Sign to store an e-Note in an eOriginal vault, integrators must add the following two fields to the transaction's data field:

eOriginal vaults an e-Note from a OneSpan Sign transaction together with the transaction's Audit Log.

If a mortgage transaction has one SMART Document and one or more PDFs: (1) an eOriginal vault can store all those documents for the transaction; (2) eOriginal's Audit Trail lists all events related to the transaction and its multiple documents.

enote_data_section

This field contains a base64-encoded XML string. That string contains enough information to create the SMART Document (including the loan's value, the borrower's details, and the address of the mortgaged property).

This field must be formatted using the XML format in the Data > Main section of the MISMO SMART Document 1.02 specification.

Example

Here is an example of a Base64-decoded enote_data_section value:

<LOAN MISMOVersionIdentifier="2.3">
    <_APPLICATION>
        <LOAN_PRODUCT_DATA>
            <LOAN_FEATURES LienPriorityType="FirstLien" LoanMaturityDate="2030-01-01" OriginalPrincipalAndInterestPaymentAmount="1111.99" ScheduledFirstPaymentDate="2020-01-01">
                <LATE_CHARGE _GracePeriod="15" _Rate="5.000"></LATE_CHARGE>
                <NOTE_PAY_TO _City="Springfield" _PostalCode="99999" _State="MI" _StreetAddress="5555 Example Drive"></NOTE_PAY_TO>
            </LOAN_FEATURES>
        </LOAN_PRODUCT_DATA>
        <MERS MERS_MINNumber="100316200000000012"/>
        <MORTGAGE_TERMS LenderLoanIdentifier="999999999" NoteRatePercent="5.300" OriginalLoanAmount="205000.00" PaymentRemittanceDay="1"></MORTGAGE_TERMS>
        <PROPERTY _City="Greenfield" _County="Green" _PostalCode="00000" _State="CA" _StreetAddress="100 Main Street">
            <PARSED_STREET_ADDRESS _HouseNumber="100" _StreetName="Main Street"></PARSED_STREET_ADDRESS>
        </PROPERTY>
        <BORROWER BorrowerID="N1001" NonPersonEntityIndicator="N" _FirstName="Homer" _LastName="Homeowner" _MiddleName="J." _SSN="555555559" _SequenceIdentifier="1" _UnparsedName="HomerJHomeowner"></BORROWER>
        <BORROWER BorrowerID="N1002" NonPersonEntityIndicator="N" _FirstName="Patricia" _LastName="Purchaser" _MiddleName="P." _SSN="666666669" _SequenceIdentifier="2" _UnparsedName="PatriciaPPurchaser"></BORROWER>
    </_APPLICATION>
    <_CLOSING_DOCUMENTS>
        <EXECUTION _City="Orange" _Date="2020-01-01" _State="CA"></EXECUTION>
        <LENDER _UnparsedName="Sample Banking Group"></LENDER>
    </_CLOSING_DOCUMENTS>
</LOAN>

enote_vaulting_data

This field should be a Base-64-encoded JSON string. When the field is decoded, the parameters in the following table can be viewed.

Parameter Required? Description
vaultCredentials Yes

This JSON object contains the authentication credentials for accessing eOriginal's eCore service API. This object must contain the following required fields:

  • username — API Login ID of the API user who will perform the vault-deposit operation.
  • orgNameOrganization Short Name for the Organization within eOriginal's eCore service, where the e-Note will be stored.

  • apiKey — API User's 32-character API Key.

This JSON object also contains the following optional field (a default value will be used if the endpoint field is not specified):

  • endpoint — The eOriginal environment in which documents will be deposited. The possible values are:

    • testondemand — This is: (i) one of two values supported for Sandbox accounts; (ii) the default value for Sandbox accounts.

    • previewondemand — This is the other value supported for Sandbox accounts.

    • ondemand — This is: (i) the only value supported for Production accounts; (ii) the default value for Production accounts.

enote_name Yes Name that will be given to the e-Note in the associated OneSpan Sign transaction (and later to the e-Note in the eOriginal vault).
document_type Yes This parameter is used in eOriginal's eCore service to classify documents according to their associated process within your business. It must match a Document Type that has been configured for your eOriginal eCore service Customer Org.
loanOriginators Yes

The value of this parameter is a JSON array that must contain one or more entries, each of which has the following three elements:

  • nmlsId — Identifier assigned to the Loan Originator by the Nationwide Mortgage Licensing System And Registry
  • unparsedName — Name of the Loan Originator individual or Organization
  • nonPersonEntityIndicator — Possible values are Y and N. Y indicates that this Loan Originator data represents an Organization. N indicates that this Loan Originator data represents an individual.
version No Version of the protocol to be used. Currently the only supported value is Mortgage-2.0.
enote_template_name No

Name of the template that will be used to create the SMART Document. The supported values are:

  • template_3200_enote.xml — This is for the form Multistate Fixed Rate eNote 3200e.

  • template_3244-1_enote.xml — This is for the form Texas Home Equity eNote 3244.1.

  • template_3244-2_enote.xml — This is for the form Texas Home Equity eNote Second Lien.

additionalDocumentsToVault No

The value of this parameter is a JSON array that must contain one or more entries. Each entry: (1) contains vaulting information for a specific document; (2) must have the following required fields:

  • documentId — ID of the OneSpan Sign document that will be vaulted with eOriginal's eCore service. This document is typically a loan. The value of this parameter should match the document ID of a document in the transaction.

  • loanId — Unique ID of the loan, according to the customer's system

  • loanAmount — Original amount of the loan in US cents

  • lender — Name of the lender for this loan

  • type — Parameter used in eOriginal's eCore service to classify documents according to their associated process within your business. Must match a Document Type that has been configured for your eOriginal eCore service Customer Org.

postRegisterOption No

After the authoritative copy of a document is vaulted in an eOriginal vault, it is removed from OneSpan Sign. This parameter specifies how this authoritative copy will be replaced in OneSpan Sign. The supported values are:

  • watermark_doc (default) — After a document is vaulted, the signed PDF content is watermarked, flattened, and saved in OneSpan Sign.

  • blank_doc — After a document is vaulted, the signed PDF content is replaced in OneSpan Sign with a blank document.

Note: Clients cannot download the authoritative copy of a document that will be deposited in an eOriginal vault. If they try to do so, they will end up downloading a flattened non-authoritative copy whose every page will bear the watermark Non-Authoritative Copy.

customFields No

This JSON object contains data that will be added to the eOriginal transaction as Custom Fields.

This object can contain any field as long as its name matches that of a Custom Field configured for your eOriginal eCore service Customer Org.

Example

Here is an example of a Base64-decoded enote_vaulting_data value:

{
    "version": "Mortgage-2.0",
    "vaultCredentials": {
        "username": "SampleUsername",
        "orgName": "SampleOrganization",
        "apiKey": "ok0Sample0ApiKey0Just0An0Example",
        "endpoint":"testondemand"
    },
    "enote_name": "enote",
    "enote_template_name": "template_3200_enote.xml",
    "document_type": "eNote",
    "loanOriginators": [{
        "nmlsId": "1000000",
        "unparsedName": "Sample Lender Person",
        "nonPersonEntityIndicator": "N"
    },
    {
        "nmlsId": "1323233",
        "unparsedName": "Sample Lender Corp.",
        "nonPersonEntityIndicator": "Y"
    }],
    "customFields": {
        "externalId":"123ABC",
        "customField2":"value"
    },
}

Using a OneSpan Vault

To instruct OneSpan Sign to store an e-Note in a OneSpan vault, integrators must add the following two fields to the transaction's data field:

enote-data-section

This field contains a base64-encoded XML string. That string contains enough information to create the SMART Document (including the loan's value, the borrower's details, and the address of the mortgaged property).

This field must be formatted using the XML format in the Data > Main section of the MISMO SMART Document 1.02 specification.

Example

Here is an example of a Base64-decoded enote_data_section value:

<LOAN MISMOVersionIdentifier="2.3">
    <_APPLICATION>
        <LOAN_PRODUCT_DATA>
            <LOAN_FEATURES LienPriorityType="FirstLien" LoanMaturityDate="2030-01-01" OriginalPrincipalAndInterestPaymentAmount="1111.99" ScheduledFirstPaymentDate="2020-01-01">
                <LATE_CHARGE _GracePeriod="15" _Rate="5.000"></LATE_CHARGE>
                <NOTE_PAY_TO _City="Springfield" _PostalCode="99999" _State="MI" _StreetAddress="5555 Example Drive"></NOTE_PAY_TO>
            </LOAN_FEATURES>
        </LOAN_PRODUCT_DATA>
        <MERS MERS_MINNumber="100316200000000012"/>
        <MORTGAGE_TERMS LenderLoanIdentifier="999999999" NoteRatePercent="5.300" OriginalLoanAmount="205000.00" PaymentRemittanceDay="1"></MORTGAGE_TERMS>
        <PROPERTY _City="Greenfield" _County="Green" _PostalCode="00000" _State="CA" _StreetAddress="100 Main Street">
            <PARSED_STREET_ADDRESS _HouseNumber="100" _StreetName="Main Street"></PARSED_STREET_ADDRESS>
        </PROPERTY>
        <BORROWER BorrowerID="N1001" NonPersonEntityIndicator="N" _FirstName="Homer" _LastName="Homeowner" _MiddleName="J." _SSN="555555559" _SequenceIdentifier="1" _UnparsedName="HomerJHomeowner"></BORROWER>
        <BORROWER BorrowerID="N1002" NonPersonEntityIndicator="N" _FirstName="Patricia" _LastName="Purchaser" _MiddleName="P." _SSN="666666669" _SequenceIdentifier="2" _UnparsedName="PatriciaPPurchaser"></BORROWER>
    </_APPLICATION>
    <_CLOSING_DOCUMENTS>
        <EXECUTION _City="Orange" _Date="2020-01-01" _State="CA"></EXECUTION>
        <LENDER _UnparsedName="Sample Banking Group"></LENDER>
    </_CLOSING_DOCUMENTS>
</LOAN>

enote_attribute

This field contains a base64-encoded JSON string, which in turn contains the following parameters.

OneSpan vaults are administered by the company's e-Vault Manager product.

Parameter Required? Description
enote_name Yes Name that will be given to the e-Note in the associated OneSpan Sign transaction (and later to the e-Note in the e-Vault Manager)
org_uid Yes Unique ID of the Organization. This is the same Organization ID used by users when they log into the e-Vault Manager console.
vault_id Yes Numerical ID of the vault in which the e-Note will be stored. An Organization Administrator can see the vault ID by viewing the vault's details in the e-Vault Manager console.
transaction_name Yes Name that will be given to the e-Vault Manager transaction used to register the e-Note with the e-Vault Manager
loanOriginators Yes

The value of this parameter is a JSON array that must contain one or more entries, each of which has the following three elements:

  • nmlsId — Identifier assigned to the Loan Originator by the Nationwide Mortgage Licensing System And Registry

  • unparsedName — Name of the Loan Originator individual or Organization
  • nonPersonEntityIndicator — Possible values are Y and N. Y indicates that this Loan Originator data represents an Organization. N indicates that this Loan Originator data represents an individual.
enote_template_name No

Name of the template that will be used to create the SMART Document. The supported values are:

  • template_3200_enote.xml — This is for the form Multistate Fixed Rate eNote 3200e.
  • template_3244-1_enote.xml — This is for the form Texas Home Equity eNote 3244.1.

  • template_3244-2_enote.xml — This is for the form Texas Home Equity eNote Second Lien.

Example

Here is an example of a Base64-decoded enote_attribute value:

{
    "enote_name": "enote",
    "enote_template_name": "template_3200_enote.xml",
    "transaction_name": "t",
    "org_uid": "org1",
    "vault_id": "1",
    "loanOriginators": [{
        "nmlsId": "1000000",
        "unparsedName": "Sample Lender Person",
        "nonPersonEntityIndicator": "N"
    },
    {
        "nmlsId": "1323233",
        "unparsedName": "Sample Lender Corp.",
        "nonPersonEntityIndicator": "Y"
    }]
}

Email Template for a Vaulting Failure

If an attempt to vault an e-Note fails, OneSpan Sign uses the following template to send the associated transaction's Sender an email about the failure.

This template cannot be customized.

<?xml version="1.0" encoding="UTF-8"?>
<email-template xmlns="urn:schema.awsng.silanis.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<from>
<email>[email protected]</email>
<display_name>OSS Support</display_name>
</from>
<to>
<address>
<email>%USER_EMAIL;</email>
<display_name>%USER_FIRST_NAME; %USER_LAST_NAME;</display_name>
</address>
</to>
​
<subject>e-Sign Ceremony Failure Notification</subject>
<body>
<content-type>text/html; charset="UTF-8"</content-type>
<content>
​
Dear %USER_FIRST_NAME; %USER_LAST_NAME;,<br/>
<br/>
An error has occurred for your package: <br/>
<br/>
%NOTIFICATION_MESSAGE;<br/>
<br/>
Should you have any problem, please contact OSS Support at [email protected]
.<br/>
<br/>
​
Thank you for e-signing.<br/>
<br/>
​
OSS Support
</content>
</body>
<priority>1</priority>
​
</email-template>

The above failure notification will not be sent if any of the following errors occurs within the vaulting_data JSON field:

Error What the POST request /api/packages returns
The documentId field for the parameter documentsToVault is incorrect (i.e., it is not a documentID in the transaction). 200
The username field for the parameter vaultCredentials is incorrect. 200
The apiKey field for the parameter vaultCredentials is incorrect.

500

"messageKey": "error.internal.default","technical": "error.eslx.validation.eoclient.loginError”

The orgName field for the parameter vaultCredentials is incorrect, but the apiKey field is correct.

500

"messageKey": "error.internal.default","technical": "error.eslx.validation.eoclient.loginError”

Incorrect JSON – e.g., referencing vaultCredentials as valutCredentials. 200
Was this information helpful?
X