API - Searching Customers

To search customers a POST request is sent to the Customers/Autopal.Search() endpoint, often with request flags to determine what to show in the results. This endpoint takes a JSON object as the body to describe how and what to search. Below is an example:

POST https://loanpro.simnang.com/api/public/api/1/Customers/Autopal.Search()?$top=25&$start=0&$orderby=id%20asc
{
"query": {
"bool": {
"must": [
{
"bool": {
"should": [
{
"query_string": {
"query": "*brett*",
"default_operator": "AND",
"fields": [
"customerName",
"email",
"ssn",
"city",
"zipcode",
"state",
"employer.companyName",
"primaryPhone",
"customId",
"customFields",
"accessUserName"
]
}
}
]
}
}
]
}
},
"aggs": {
"avg_loanscount": {
"avg": {
"field": "loansCount"
}
},
"avg_creditscore": {
"avg": {
"field": "creditScore"
}
},
"avg_paymentmethodscount": {
"avg": {
"field": "paymentAccountsCount"
}
},
"avg_referencescount": {
"avg": {
"field": "referencesCount"
}
}
},
"sort": {
"id": "asc"
}
}

The results section shows the returned customer(s), the summary section holds a summary of basic information concerning the results.

Pagination

Often, pagination is desired due to the large amount of results that are returned. Pagination allows integrations to work on small chunks of data at a time instead of loading all of it into memory.

With pagination, there are two main URL query parameters: $start and $top.

$start

$start defines the offset to start returning results with. $start assumes that result indexing starts with 0. This means that $start=0 will return results starting with the 1st result, and $start=25 will return results starting with the 26th element. This is similar to the way arrays work in languages like C/C++, C#, Java, Javascript, etc.

$top

$top defines the number of results to return. $top gives the upper bound on the number of results that will be returned. For example, $top=20 will return up to 20 results, and $top=100 will return the first 100 results.

Combining

For example, assume you want page sizes of 30 results each. With this, you would get the following:

Page 1

$start=0,$top=30

Page 2

$start=30,$top=30

Page 3

$start=60,$top=30

Page 4

$start=90,$top=30

Ordering

Often times, integrations want to process data in orders other than the default ordering provided by LoanPro. This can be done by setting the URL query $orderby variable. The value of the $orderby variable is formatted as “<variable> <direction>”. In the format, “<variable>” is the result field to sort the results by. For example, to sort customers by stoplights, you would set “<variable>” to be “stoplight”. For “<direction>”, it will be either “asc” for ascending ordering or “desc” for descending ordering.

For example, to order by the stoplight field in ascending order, you would use $orderby=stoplight asc. To order by the stoplight field in descending order, you would use $orderby=stoplight desc.

Q&A

Question:

I would like to be able to search by Customer ID and get back the full customer entity.   

I’m using Postman against your public test sandbox instance, and submitting this query where 653 is the id of a customer I created:

{ “query”: { “bool”: { “must”: [ { “query_string”: { “query”: “653", “fields”: [ “id” ] } } ] } } }

Based on the below, I also tried “customId” as the field to match, but the search

returns 154 total hits, none of which are Customer ID of 653.

I also created a new customer and then tried the below search to make sure I was using a unique field value from the list of fields for ElasticSearch customer queries, with the same results:

{ "query": { "bool": { "must": [ { "query_string": { "query": "SomeEmail@nowhere.com", "fields": [ "email" ] } } ] } }

Assuming ElasticSearch is configured to work normally in the public test/sandbox instance, can you please let me know where I’m going wrong with the query construction?

Answer:

The best way to accomplish this is not to use Elasticsearch, but to use the /odata.svc/Customers() endpoint. Elasticsearch searches lots of data for the numeric ID, but none of the fields it searches are the ID field specifically. To pull a customer with ID 653, use this endpoint:

GET https://loanpro.simnang.com/api/public/api/1/odata.svc/Customers(653)

This will get you the exact Customer that you need.

Question:

Could you provide as soon as possible, example payloads using ElasticSearch to return from your public sandbox instance all customer entities matching:

  • email address
  • phone number
  • first name and last name
Answer:

This payload should return the single account with this email address:

{
"query":{
"bool":{
"must":[
{
"bool":{
"should":[
{
"query_string":{
"query":"SomeEmail@anywhere.com",
"default_operator":"AND",
"fields":[
"email"
]
}
}
]
}
}
]
}
},
"sort":{
"id":"desc"
}
}

To search by phone number for the same account use this payload:

{
"query":{
"bool":{
"must":[
{
"bool":{
"should":[
{
"query_string":{
"query":"4899727891",
"default_operator":"AND",
"fields":[
"primaryPhone"
]
}
}
]
}
}
]
}
},
"sort":{
"id":"desc"
}
}

Finally, to get the same account searching by first name and last name, use this payload:

{
"query":{
"bool":{
"must":[
{
"bool":{
"should":[
{
"query_string":{
"query":"(John AND Doe)",
"default_operator":"AND",
"fields":[
"customerName"
]
}
}
]
}
}
]
}
},
"sort":{
"id":"desc"
}
}

This will return more than the single result, because there are more customers with this exact name.


How did we do?


Powered by HelpDocs (opens in a new tab)