API – Document Upload

Introduction

This article explains how to upload documents through the API, but you can also upload common and customer-specific documents within the LoanPro UI.

Uploading a document through the API is a two-step process:

1. Send a POST to receive a pre-signed S3 upload URL
2. Upload the document to S3 using the pre-signed URL

At this point, you can make changes to the document properties

Get a Pre-Signed URL

To get a pre-signed URL, send a POST request to either of the following URLs, depending on whether you are uploading a loan document or a customer document:

POST https://loanpro.simnang.com/api/public/api/1/Loans({ID})/document/upload 

or

POST https://loanpro.simnang.com/api/public/api/1/Customers({ID})/document/upload

Your JSON payload will look something like this:

{
  "sectionId": 1,
  "fileName": "test.jpg",
  "size": 160000,
  "customFileName": "other_name.jpg"
}

Here's an explanation of each field:

• sectionId (required) - The ID of the document section. This must be an ID that exists within your LoanPro account.
• fileName (required) - Name of the file that will be uploaded. This must match the actual file name.
• customFileName (optional) - Custom file name. This doesn't need to match the actual file name, and will be a label used in LoanPro.
• size (optional) - Size of the file in bytes.

A 200 response will look like this:

{
  "d": {
    "id": "89",
    "fileName": "test_1572647511.jpg",
    "uploadUrl": "https://autopal-fandora.s3.amazonaws.com/tenants/1/fileAttachments/LoanDocuments/89/test_1572647511.jpg?
X-Amz-Content-Sha256=UNSIGNED-PAYLOAD
&X-Amz-Algorithm=AWS4-HMAC-SHA256
&X-Amz-Credential=AKIAQ5VMVMN6QS2AAJZF%2F20191101%2Fus-east-1%2Fs3%2Faws4_request
&X-Amz-Date=20191101T223152Z
&X-Amz-SignedHeaders=host
&X-Amz-Expires=600
&X-Amz-Signature=fd63f88946e626ec7fbea9d1711ca3078bf42ee507d456b487caebb5b7bdca72",
    "customFileName": "test.jpg",
    "mime": "image/jpeg"
  }
}

The response includes the following:

• id - The ID of the created Document.
• fileName - System-generated unique filename (usually the file name with a number appended).
• customFileName - Name provided in the request payload.
• mime - Identified MIME type based on the file extension.
• uploadUrl - S3 URL where the file must be uploaded. This link has an expiration time of 10 minutes.

StackBlitz Example

Many of our articles use StackBlitz examples like this. These examples are like a window into a REST client right here in your browser. The window is divided into two sides. Developers can use info in the editor on the left side when configuring your API integration, and the right side shows a preview of a REST client. Click 'Preview' on the bottom, and you'll only see the REST client.

The entire request is set up and connected to a demo API tenant in LMS. Just scroll down and click 'send' and you should get a 200 response. If you want to get some practice with error codes, try editing the endpoint, headers, method and payload to see what responses you get.

Upload the File

Now that you've sent that POST request, you've primed the system to receive your actual file. Instead of the endpoint we used on the first request, we send a PUT request with the file to the S3 URL you received in the last response. You'll also remove the normal authorization and Autopal-Instance-Id from your header.

Here is a cURL example:

curl --upload-file "/home/user/Documents/send/test.jpg" 
"https://autopal-fandora.s3.amazonaws.com/tenants/1/fileAttachments/LoanDocuments/89/test_1572647511.jpg?X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAQ5VMVMN6QS2AAJZF%2F20191101%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20191101T223152Z&X-Amz-SignedHeaders=host&X-Amz-Expires=600&X-Amz-Signature=fd63f88946e626ec7fbea9d1711ca3078bf42ee507d456b487caebb5b7bdca72"

Updating Documents

To update a document, send a PUT request to the URL of the document. For Loan documents, it is:

https://loanpro.simnang.com/api/public/api/1/odata.svc/LoanDocuments(id=<id>)

and for customer documents it is:

https://loanpro.simnang.com/api/public/api/1/odata.svc/CustomerDocuments(id=<id>)

In both cases, replace “<id>” with the ID of the document.

Changing Active Status

To inactivate a document, the "archived" property should be changed from a 0 to a 1. To do this, send a PUT request with a body that looks something like the following:

{
  "id": 59,
  "archived": 1,
  "__update": true,
  "__id": 59
}

Changing Customer Visibility

To change the customer visibility of the document, send a PUT request with the body formatted as follows:

{
  "id": 59,
  "customerVisible": 1,
  "__update": true,
  "__id": 59
}

• customerVisible – Set to “1” to allow the customer to see the document on the customer website
• id – The ID of the document being updated

Updating Metadata

To update the metadata of a document, send a PUT request with the body formatted as follows:

{
  "id": 76,
  "sectionId": "5",
  "description": "this is a description",
  "fileName": "test.png",
  "__id": 76,
  "__update": true
}

• id – The ID of the document to update
• sectionId – The document’s section ID
• description – The description for the document
• fileName – The file name for the document