Moneylender API Setup and Overview
Moneylender's built-in API functions similarly to other JSON-based financial services APIs across the industry. Submit and request data using HTTPS requests. Request details can be supplied through the query string or in the request body. Each URL of the API supports a different operation in Moneylender.
Configuring the Host Computer
Run as Administrator
In order to use the API, the host instance of Moneylender must be run as administrator. You can create a shortcut to "C:\Program Files (x86)\Moneylender 3 Professional\Moneylender3.exe" and then set the shortcut to always start the program as an administrator for extra convenience (right-click the new shortcut, click Properties, click Advanced, check the box for Run as Administrator). If not running as administrator, Moneylender will be closed by Windows as soon as it tries to start listening for HTTPS connections.
Configure SSL Certificate
You need to configure your Portfolio to use a specific port and assign an SSL certificate to use for encryption on the API. The API cannot be accessed through non-encrypted HTTP requests.
You will need to install a certificate in the Machine\Personal certificate store. You can manage your certificates from Window’s built-in certificate manager. To open the certificate manager, click the Windows button and type “cert”. Click the option “Manage computer certificates”. It’s pretty easy and inexpensive to get a certificate that matches your domain if you don’t already have one – you can also use whatever certificate you already have (such as localhost or a self-signed certificate). I get my web hosting certificates from ssls.com – their cheapest option is perfectly sufficient for use with the Moneylender API.
In general, you'll want the certificate name to match the name your software will use to access the API – for example, “localhost” or “mylenderwebsite.com”. If you will use a certificate that doesn’t perfectly match the hostname used by your software to access the API, you can usually configure your software to proceed in spite of the name mismatch on the certificate. Be sure that your systems are set up so that a malicious user wouldn’t be able to hijack the connection between the API and your software in this case.
Once you have your certificate installed in the machine store under the Personal group, you can use Moneylender to register that certificate to the API port. In Moneylender with your portfolio open, click Portfolio > Portfolio Settings > Network tab. Enable the API, enter the desired port and click “Attach Certificate to API Port”. Select your certificate from the Machine store and click “Choose”. When you click this button, Moneylender will register itself and this certificate to Windows for receiving incoming HTTPS requests.
The certificate browser that opens lists the certificates Windows has on this computer. Pick User Store or Machine Store to choose which certificate store to look in (the API needs the certificate in the Machine store), click the certificate on the list, and click .
Check the box to enable the API, and check the box to Automatically Open to the Network so Moneylender will begin listening for API connections as soon as the portfolio opens from now on. Finally, tell Moneylender to start listening for connections from Portfolio > Make Available on Network.
Adding a User Account to Grant the API Access to Your Portfolio
The API will log into Moneylender using a portfolio user account. You manage these from Portfolio > Configure Portfolio Users. Add an account and be sure to apply the required API permissions. The login ID and password you enter for the user account are the login ID and password you’ll use to access the API.
Connecting to the API
At this point, Windows knows to forward HTTPS requests to Moneylender on the API port. You can open a web browser and navigate to the API. For example, https://localhost:18014. If you connect successfully to the API, you’ll see the internal documentation. The documentation explains the function of each URL of the API, and you can use the links to browse all the available URLs.
Supplying Credentials and Parameters
Every parameter the API accepts, including the loginid and password sent to /login and the token sent with every other request, can be supplied in any of three places. The API checks the query string first, then a form-encoded request body (Content-Type: application/x-www-form-urlencoded), then a top-level property of a JSON object in the request body. The token may also be sent as an Authorization: Bearer header. Sending credentials in the body or the header keeps them out of proxy logs and browser histories.
URLs that already take a JSON payload in the body (record edits and searches, the payment calculator) continue to work as they always have. A token property placed alongside the payload is recognized as the token. A search whose body is a bare JSON array has no place for a token, so send it in the query string or the header for those requests.
Running Reports Through the API
The /reports URLs run any report saved in Reports > Report Manager, or a whole batch from Reports > Report Batches, and hand back the finished file. The account used needs the API Execute Operations permission plus Run Loan Reports or Run Portfolio Reports, the same permissions the desktop checks.
- /reports/run runs one report by its ReportTemplateID. You can override the date range with a preset such as PreviousMonth or with custom start and end dates, pick the loan for a single-loan report, and choose the account, loan status and lender. The response is the CSV (or PDF) itself.
- /reports/runbatch runs every report in a batch by its ReportBatchID and returns a zip of the files, exactly as the web client's Run Batch does.
The saved reports and batches are ordinary records, so their IDs and settings come from the records URLs: /records/ReportTemplate, /records/ReportBatch and /records/ReportBatchReport.
Saving to disk instead of streaming. A self-hosted portfolio can let the API save reports on the host computer. Set File > Moneylender Settings > General > API Report Folder on the computer that hosts the portfolio, then pass output=file. The API never accepts a folder or file name from the caller: single reports land in that folder under the report viewer's export name, and batches in a dated subfolder, the same layout the desktop batch runner uses. Leave the setting blank and the API only streams. Portfolios hosted by Whitman Technological are always stream-only.
Long-running reports. A report that takes more than a minute or two should not be run on an open HTTP connection, because most clients give up after 100 seconds and network equipment drops idle connections well before a slow report finishes. Add async=true to /reports/run or /reports/runbatch and the API answers at once with a ticket. Poll /reports/status every 10 to 30 seconds for the state and percent complete, collect the file from /reports/result once the state is ready, or stop the job with /reports/cancel. Tickets belong to the user account rather than the token, so a token that expires during a long run just means logging in again and continuing to poll. Full parameter tables and examples are on the API's own /reports page.
Moneylender's Database Architecture
Refer to the diagram below for an illustration of the relationships between the different records. Each Loan record has a multitude of Setting records that define the various characteristics of the loan’s terms at various points in time. A basic loan usually consists of the loan record, plus a principal setting, interest setting, payment setting (not to be confused with payment records that denote the receipt of money from the borrower), and a late fee setting. Any loan can have multiple settings of every type. Some settings can overlap each other (such as late fees and other fees) and some settings supersede each other (such as payment settings, interest settings, and escrow charges).
Browse the API's Internal Documentation
We're hosting an instance of the API on our server so you can see what the internal structure looks like. In our instance of the API, you won't have a loginid or password to authenticate and get a token, but you can read all the details of what the API can do.