Introduction

The LMS API will often respond with objects that contain a list of items rather than just a single item. This is most common with the following:

• GET requests to OData endpoints where an ID is not specified 
• POST requests to Elasticsearch search endpoints 

Response Objects with Multiple Results

By default, OData will return 50 results and Elasticsearch will return 10. These defaults are in place to limit endpoint bandwidth and lower response times while still providing an abundant amount of information.

However, removing these limits may be necessary in certain circumstances. On this page, we'll describe how to use endpoint parameters so that you can filter the information you receive in your requests.

Let's begin by looking at an example OData endpoint:

https://loanpro.simnang.com/api/public/api/1/odata.svc/Payments?$filter=entityId eq 5919&$top=30

This is an example of the Payments endpoint with a few filtering parameters.

LMS endpoint parameters are tacked on to the endpoint URL by first adding a single question mark (?) at the end of the URL before the parameter list. Then, the parameter name is added and is preceded by a dollar sign ($). The parameter name is followed by an equals sign (=) and a value. Lastly, if you are using multiple endpoint parameters, an ampersand (&) is placed between each one. Listed below is the order of a parameter list as well as examples of endpoints with parameters.

Here's an example OData endpoint:

Example	Description
https://loanpro.simnang.com/api/public/api/1/	The base URL for all LMS endpoints.
odata.svc/Payments	The OData endpoint for Payments.
?	HTTP syntax. The question mark indicates that the regular endpoint has ended, and everything that follows is an endpoint parameter that will limit or expand the results.
$filter	The parameter name. The dollar sign indicates that it is an OData token that can carry out a specific function beyond a normal parameter that simply holds a value.
=entityId eq 5919	The value. The equals sign connects this to the parameter name that preceded it.
&	HTTP syntax. The ampersand distinguishes between parameters.
$top	A second parameter name, indicating how many results should be shown.
=30	The value matching the $top parameter name. It tells the system we want the top 30 entries.

And here's an example Elasticsearch endpoint:

Example	Description
https://loanpro.simnang.com/api/public/api/1/	The base URL for all LMS endpoints.
Loans/Autopal.Search()	The Elasticsearch endpoint for searching loans.
?	HTTP syntax. The question mark indicates that the regular endpoint has ended, and everything that follows is an endpoint parameter that will limit or expand the results.
$start	The parameter name, indicating where the results should begin.
=20	The value paired to the preceding parameter. In this case, it tells the system to start the results at the twentieth entry.
&	HTTP syntax. The ampersand distinguishes between parameters.
$top	A second parameter name, indicating how many entries should be shown.
=30	The value matching the $top parameter name. It tells the system we want the top 30 entries.

Paging with OData Requests

Set Page Size

Setting a page size allows you to determine a maximum number of results you'd like to receive. To do so, you can use the $top parameter within your requests. This does not guarantee that the specified amount of results will be returned, and it will not change the order the items are returned. But it will guarantee that no more than the specified number of items are returned.

https://loanpro.simnang.com/api/public/api/1/odata.svc/Payments?$filter=entityId eq 5919&$top=200

Skip and Skiptoken

We've covered altering the page size, but what` about retrieving results from a specified point and beyond? To achieve this, use the $skip and $skiptoken parameters. The $skip parameter allows you to do exactly that: skip however many results you'd like and return the results that follow.

https://loanpro.simnang.com/api/public/api/1/odata.svc/Payments?$filter=entityId eq 5919&$skip=50

Where $skip specifies a static number of results to skip, $skiptoken allows you to specify an exact ID from the database for the entity to skip past and return the results that follow.

https://loanpro.simnang.com/api/public/api/1/odata.svc/Payments?$filter=entityId eq 5919&$skiptoken=239898

Both $skip and $skiptoken are non-inclusive, meaning wherever you skip to will not be included in the results (e.g. $skip=50 will not include result 50; returned results will start at 51)

Filter

The $filter parameter allows you to restrict the result set that will be returned without having to use an Elasticsearch query object.

This parameter can be used on any property returned in a list item for the endpoint and follows this basic structure:

Here's a breakdown of each section of the endpoint:

Example	Description
https://loanpro.simnang.com/api/public/api/1/	The base URL for all LMS endpoints.
odata.svc/Payments	The OData endpoint for Payments.
?	HTTP syntax. The question mark indicates that the regular endpoint has ended, and everything that follows is an endpoint parameter that will limit or expand the results.
$filter	The parameter name, indicating the results limitation.
=entityId eq 5919	The value paired to the preceding parameter. In this case, it tells the system to only retrieve results who have an entityId equal to 5919.
and	Keyword to separate expressions in the same $filter parameter.
date lt datetime'2021-10-04T00:00:00'	The second value paired to the preceding parameter. In this case, it tells the system to only retrieve results who have a date that is less than the date of 10/04/2021 at 00:00:00.

The $filter parameter supports the following comparison operators: eq (equal), lt (less than), gt (greater than), le, (less than or equal to), and ge (greater than or equal to).

Additionally, any string values being compared to should be contained in single quotes ('string'). This includes any dates, datetimes, words, sentences, etc.

You can use $filter with any name:value pair from the JSON object that's returned by default in the response from the entity. For example, the response from a payment list item includes a comment field. You could add a filter token to find only the payments with a specific comment: $filter=comments eq 'A Specific Comment' 

The LMS API supports a few other OData filter parameters. Here's a list of other available parameters you can use:

Category	Available Filter Options	Syntax
Logical Operators	equals, not equals	eq, ne
	greater than, greater than or equal to	gt, ge
	less than, less than or equal to	lt, le
	and, or	and, or
	has	has
	in	in
Arithmetic Operators and Functions	addition, subtraction	add, sub
	multiplication, division	mul, div
	modulo	mod
	grouping
	floors, ceilings	floor, ceiling
	round	round
String and Collection	concatenation	concat
	string ends with, string starts with	endswith, startswith
	whitespace trimming	trim
	to lower, to upper	tolower, toupper

Select

Finally, the $select parameter allows you to list specific information for each filter result. For example, if you filter Payment information (like shown above) and would like to list the payment amount for every result, add $select=amount to your request endpoint. This is a useful tool for selecting only necessary information wihtin your responses. You can also select multiple parameters by separating each one with a comma; for example, you can use $select=id,amount,date to see the ID of a payment, the amount that was paid, and on which day.

Here's an example of the entire endpoint:

https://loanpro.simnang.com/api/public/api/1/odata.svc/Payments?$filter=entityId eq 9100&$top=200&$select=id,amount,date

Response Summary

Each OData request response will contain a small summary object with the following properties:

• start - The index at which the results list starts
• pageSize - The set page size
• total - The number of results returned in the results list

Paging with Elasticsearch Requests

Set Page Size

Setting page size in the Elasticsearch endpoints works in the same way as the OData endpoints. If you'd like to set the page size, you can do so with the $top parameter. Again, this does not guarantee that the specified amount of results will be returned, and it will not change the order the items are returned, but it will guarantee that no more than the specified number of items are returned.

https://loanpro.simnang.com/api/public/api/1/Loans/Autopal.Search()?$top=50

Start

The OData parameters of $skip and $skiptoken are not supported for the search endpoints. Instead, these requests utilize the $start parameter to specify a starting place for the results. For example, using $start for search endpoints functions the same way as $skip for OData.

https://loanpro.simnang.com/api/public/api/1/Loans/Autopal.Search()?$start=50

Response Summary

Each search request response will contain a small summary object with the following properties:

• totalHits - The total number of results returned from the query (this will not match the results contained in the results list, as this is handled with paging)
• totalTime - The amount of time it took to retrieve results

Elasticsearch Safeguard

Elasticsearch has a built-in safeguard that prevents you from paging through more than 10,000 results. This means that if the sum of your $start and $top parameters is greater than 10,000, Elasticsearch will fail to return any results.

However, you can circumvent this issue by fetching results beyond the first 10,000 with the search_after payload parameter.