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 are both vault providers 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 Java SDK.

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.

If an attempt to vault an e-Note fails, OneSpan Sign sends the Sender of the associated transaction 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.

As of the 11.37 release of OneSpan Sign, 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.
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.

Example

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

{
    "version": "Mortgage-2.0",
    "vaultCredentials": {
        "username": "SampleUsername",
        "orgName": "SampleOrganization",
        "apiKey": "ok0Sample0ApiKey0Just0An0Example"
    },
    "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"
    }]
}

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