APIs 101

Introduction

This article explains APIs in layman’s terms. If you’re totally new to the concept, you’re in the right place. Developers and other tech-minded people probably won’t need this primer, and can skip ahead to API Integration, Communicating with the API, or our other API Documentation.

What’s an API? And how does it compare to the UI?

When you log in at loanpro.io and use the Loan Management System User Interface (LMS UI), you manually click buttons and type information to interact with the software. When creating a new loan, for instance, you’ll click through different fields and enter loan information. The LMS UI looks nice and is easy to navigate, because it was designed with human users in mind.

But let’s say we want to automate things. Lots of lenders do this if they have their own customer-facing website where borrowers apply for loans. The borrower puts in their information at your website, and then your website can automatically send the information over to LoanPro. The computers don’t need a modern and intuitive UI because there are specific ways to tell the system exactly what to do. Computers can send all of that information in an instant, but they just need to know where to send it and how to format it. That’s where the API comes in.

An application programming interface (API) is something that the developers of an application make to let other programs or applications talk to their application. When an application communicates with LoanPro via our API, rather than manually clicking ‘New Loan’ and typing everything in, your software will generate a little bundle of information with all the necessary loan specifics, and send it to a designated URL. LoanPro will receive that information at the URL, and use it to create a new loan. LoanPro will send back a response saying that your loan was successfully created. 

Not only can you automate loan creation, but virtually every aspect of loan servicing can be accomplished through the API. What’s more, you can integrate the LMS API and APIs from other software applications through your middleware. Suppose you use an origination software to determine which loans should be approved. Your developers can configure your own software so that customers enter their data on your website, which then automatically sends it to your origination software. They can then send information back to you so you can send it directly to the LMS API.

Interacting with the API

APIs are meant to let computers talk to other computers. On LoanPro's end, the software is ready. But it will take some effort to configure your own software and middleware to send the correct messages to the correct places. A team of developers can help set everything up so that your system can send and receive information from LoanPro through the API.

REST Clients

To set up and test the API, individual users can interact with it as well. Instead of logging in at loanpro.io, you'll need to use what's called a 'REST client'. This is a third-party application that can send and receive messages with LMS through the API. When your developers integrate your system with LoanPro's API, they won't use a REST client, and messages will be sent directly from your software to ours. The REST client is like a public computer at the library: It's useful if you just want to see how things work, but you wouldn't manage your business from one.

REST?
The LoanPro API is a Representation State Transfer (REST) API. REST is a set of constraints on the API that govern how it works and simplify the process for users. Your developers might need more information, but for the purposes of this article, we can just say that there are different kinds of APIs and LoanPro uses a REST API.

There are lots of different REST clients out there, and many are free. Insomnia and Postman are both highly rated and free to download.

Terms

Before we dive in and send some messages to the API, it'll be helpful to explain some specialized terminology.

Term

Definition

Tenant

A tenant is your account with LMS. Normally we'd call this an "account" or "user," but both of those terms refer to something else in the software. Additionally, any number of agents can be users with the same tenant — they all share the same credentials to use the API.

Each tenant has its own database. Your data is your own, and no other LoanPro customer can access it.

Call / Request

A call or request is your message to the API. The request has several parts, like an endpoint, payload, header, body, and method, which are all defined below.

Endpoint

When you send information to the API, you need to send it to a specific place. These are endpoints, URLs that tell the system exactly where you want to send or retrieve information. Each API request, like creating a loan or creating a customer, has its own endpoint. Some API endpoints, like the one used to create a payment, use the Loans endpoint, but the payload is specific to the action being done. There are also endpoints for specific entities, like an individual customer or loan.

Some endpoints exist, but are only available within the software and are used by LoanPro's interface. They are not "whitelisted" for use by external API users. These are mostly settings-related endpoints.

Payload / Body

The payload or body is the content of your request. Generally, requests that add or update content will include a payload, but requests to retrieve or delete information will not (see Method below for a fuller explanation).

The LoanPro API uses the JSON format, which is easy for humans to read and understand. This will help you or your developers figure out what information needs to go where, or diagnose the problem if something is wrong.

Headers

In the same way that the header on any document might tell you what it is, the headers of a request specify things about the request. For example, if your request includes a body (sometimes called a payload), a header can be included that specifies the format (for LoanPro requests, this is almost always JSON).

Your headers will also include authorization information. The authorization 'token' LoanPro uses is string of numbers and letters that's unique to your LoanPro account. In the same way that you'd have to log in with a username and password to use the UI, you'll need to include your token to use the API.

These tokens are stored in the LMS UI. Navigate to Settings > Company > API > Overview. Our article API Integration explains the details.

Method

The method tells our system what you want to do. The LMS API uses GET, POST, PUT, and DELETE methods.

  • GET – You'll send this request when you want to retrieve information. GET requests do not contain a body.
  • POST – Much like posting something on a social media site, a POST request adds new content to the system. This might be creating something, or prompting the system to do something (like sending an email to a borrower or generating a report). POST requests will always have a payload.
  • PUT – Where POST requests often create something new, PUT requests will modify something that's already there. In the same way that you can log in to the UI and edit a customer's information, for instance, you can do the same through the API. PUT requests also contain a body.
  • DELETE – As the name implies, DELETE requests will remove something entirely from the system. Like GET requests, they have no payload.

Response

So far, everything in this table has been part of the request, part of your message to the API. The response is LoanPro's answer. Most REST clients will display the response right beside or below your request. The response will always include a three-digit number (called a 'status code' or 'error code', discussed below) that tells you whether the request was successful.

Usually, the response will also include a message about what the outcome was. If you created a loan or customer, it'll give you all of that entity's information. A successful GET request will pull all the information about the entity you're asking after, and the response can be rather long. A simpler request, like a DELETE, might just give you a single line saying that the item was deleted.

Status Code / Error Code

Every response from the system includes a status code, a three-digit number telling you whether the request was successful. A successful request will always give you a 200 status code.

When the request fails, the status code will usually be in the 400s. These are commonly referred to as error codes, and can be used to diagnose what went wrong with the request. If you've ever clicked an outdated link and seen a message that says "404: Page Not Found", then you've seen an error code first hand.

For security reasons, we can't publicly list what all of the error codes mean, but our article API – Error Responses explains the basics. If you encounter an error code that isn't listed here, you can contact our support team.

Sample Request and JSON Payload

Now that we've gone over the basics, let's look at an actual API request. This is the request to create a new loan. Most of the requests on help.loanpro.io are formatted like this. (See more on our help materials in the LoanPro API Documentation section below.)

Method and Endpoint

The POST method tells the system that we're adding new information. The loans endpoint is used for many of our API requests.

POST https://loanpro.simnang.com/api/public/api/1/odata.svc/Loans

Headers

The content-type header tells the system that your payload is in the JSON format. The Authorization and Autopal Instance ID are the tokens specific to an API tenant. These tokens connect you to our demo API tenant, but our API Integration article explains how to find the tokens for your own.

Content-Type: application/json
Authorization: Bearer f2baf317eb45527580d1da1d258a79c7507124d5
Autopal-Instance-Id: 5200243

JSON Payload

This payload has only the required elements — it's the bare minimum for creating a loan. For a more robust payload with all the available options, see our article API – Create a Loan.

{
"displayId": "L-z0k748522154",
"LoanSetup": {
"loanClass": "loan.class.carLoan",
"loanType": "loan.type.installment",
"loanAmount": 15000,
"loanRate": 12.0212,
"loanRateType": "loan.rateType.annually",
"loanTerm": 36,
"contractDate": "2021-05-12",
"firstPaymentDate": "2021-06-11",
"paymentFrequency": "loan.frequency.monthly"
}
}

Let's take a closer look at this payload. One of the first things you might notice are the { } curly brackets at the beginning and end of the payload. A pair of brackets show that everything within them is connected; all these values are a single object. This outermost layer of brackets tells the system where your message begins and ends.

You'll also notice that every line has two parts, separated by a : colon. This is called a name/value pair, or key/value pair. The name is on the left, surrounded by " " double quotation marks. The name defines the pair, like a label on a jar. The value, on the right, is like the contents of the jar. For example, "loanAmount" is a name; it defines this pair as the amount of money borrowed. The value, 15000, means that the borrower took out a loan for $15,000.

The value is flexible — a borrower could just as easily take out a loan for any other amount. The name, however, is not flexible. It must be written exactly. It needs to be in double quotation marks, be written in the exact same case, and have no extra spaces or dashes. The system will not understand any change to a name.

Looking closer, you'll see another set of brackets, opening after "LoanSetup" and closing after "paymentFrequency". You'll also notice that from the third line down, all the new lines are indented. The brackets and indentation are ways of showing that all of those name/value pairs (from "loanClass" down to "paymentFrequency") are part of an object; they are all a single value, in a pair within "LoanSetup".

The brackets are an essential part of the JSON payload: Without them, the system will not understand that the name/value pairs within the brackets are part of a larger object. The indentation, however, is not required. New lines and indents are just 'white space,' meaning they don't add any meaning or interrupt the payload. If a computer is sending this API request to another computer, they'll probably send it without any new lines or indents. When humans look at JSON payloads, we usually add white space to make it easier to read and understand. There are lots of websites that can add white space and 'prettify' payloads. Many of our developers use JSON Formatter or Curious Concept.
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.

More on StackBlitz
StackBlitz isn't strictly for APIs; it actually lets you input any kind of in-browser programming, and we've just made one for a web-based REST client. We like to use StackBlitz so that developers can see precisely what went into building an API call.

LoanPro's API Documentation

LoanPro has our API documentation in two places. One is help.loanpro.io, the site you're on now. Powered by HelpDocs, it houses over a thousand articles detailing how to use all of our products. It's also organized by topic; if you're reading this, you're probably interested in the folders for API Basics, LMS API, and Secure Payments API.

The other site, loanpro.readme.io, is geared toward testing the API. Each article contains endpoints, headers, payloads, and responses (200s and error codes). These articles also feature a 'Try it' button that will test it out on our demo API tenant.


How did we do?


Powered by HelpDocs (opens in a new tab)