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.
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 for Digital Mortgage Transactions
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:
This JSON object also contains the following optional field (a default value will be used if the endpoint field is not specified):
|
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:
|
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:
|
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:
loanId, loanAmount, and lender are only sent to eOriginal for the first item in the array. For subsequent items these values are not sent to eOriginal. |
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:
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" }, }
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 | |
enote_template_name
|
No |
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 |