Customer Lookup
Once you have created an order, the next step in the Application Process is to lookup the customer with their personal information to see if they are an existing Koalafi customer.
Benefits of looking Customer up:
- Determine if they have an App in Progress and can skip Apply
- Determine if they have an OpenLine (OTB)
- Determine if a customer is ineligible to Apply with Koalafi
An example customer query looks something like the following where $input represents a JSON graphQL variable.
query customers($input: CustomerSearchInput!) {
customer(input: $input){
customers{
id
}
eligibility{
isEligible
isLoanEligible
isLeaseEligible
application {
lease {
status
declineReason
draftStep
}
loan{
status
id
}
}
}
customerSearchErrors{
__typename
... on BadRequest{
message
}
}
}
}
There are a few different inputs you can use to query customer and you will need to take different actions based on what is returned. We've broken out the different recommended queries and their scenarios into different sections so that it's easier to understand.
Customer Query by Phone Number
The simplest input you can include in the customer query is the following:
{
"input":{
"cellPhone": "5555555555",
"orderId":"<orderID>"
}
}
However, this result of the query will only give you the bare minimum of available information. Unless the customer is completely new to Koalafi, you will have to make an additional customer query with more fields in the input as in the section below.
We recommend using this simplified input when you only have access to a customer's phone number. If you have access to their DOB or taxID you should make only one combined query which is covered in the section below.
If you do choose to query customer with only phone number, you can use the flow diagram below to determine your next action based on the response.
Customer Query by Phone Number, DOB and TaxID
Use the customer query to look up the customer by their mobile phone number (required) , DOB, last 4 tax ID or tax ID. Here's an example input:
{
"input":{
"cellPhone": "5555555555",
"birthDate": "1999-01-01",
"taxIDLast4": "1111",
"orderId":"<your orderID>
}
}
If the applicant is a returning Koalafi customer, the query will return additional application and eligibility data to let you know what type of financing the applicant is eligible for at this time. You can use the below flow diagram to determine which scenario your customer falls under
Scenarios:
- New Customer
- Existing Koalafi Customer
- Customer eligible to apply for financing
- Customer with an app in progress
- Customer with open line (OTB)
- Customer ineligible for financing
New Customer
The response for this scenario will look like the following:
{
"data": {
"customer": {
"customers": [],
"eligibility": null,
"customerSearchErrors": []
}
}
}
This means that we do not recognize them as a Koalafi customer and you can skip to the next page Apply for Financing
Existing Koalafi Customer
For these scenarios, we have identified the applicant as a returning Koalafi customer, but we need to take specific actions based on their eligibility. Use the flow digram above to help determine which scenario your applicant fits into based on the returned response.
Customer Eligible for Financing
A response for this scenario may look something like:
{
"data": {
"customer": {
"customers": [
{
"id": 22504,
"firstName": "Wally",
"lastName": "Koala",
"cellPhone": "5555555555",
"emailAddress": "[email protected]",
"tokenizedTaxId": "4b417418-f6e7-4dca-9919-55ae404de9f0",
"birthDate": "1999-01-01",
"billingAddress": {
"line1": "424 Hull St",
"line2": null,
"city": "Richmond",
"state": "VA",
"zip": "23224"
}
}
],
"eligibility": {
"applyTypes": [
"loanTraditional",
"leaseTraditional"
],
"otbProducts": {
"loanOptions": [],
"leaseOptions": []
},
"isEligible": true,
"isLoanEligible": true,
"isLeaseEligible": true,
"application": null
},
"customerSearchErrors": []
}
}
}
We know this customer is an existing customer eligible for financing because isEligible is true, there are no otbProducts options present and applyTypes is populated.
In this scenario, we have identified the customer as an existing Koalafi customer who is eligible to submit a new application for financing. You can skip to the next page Apply for Financing
Customer with an App In Progress
If application is not null, then the applicant has already been approved and does not need to apply for financing again. An example of a response with an application in progress will look like:
{
"data": {
"customer": {
"customers": [
{
"id": 22504,
"firstName": "Wally",
"lastName": "Koala",
"cellPhone": "5555555555",
"emailAddress": "[email protected]",
"tokenizedTaxId": "4b417418-f6e7-4dca-9919-55ae404de9f0",
"birthDate": "1999-01-01",
"billingAddress": {
"line1": "424 Hull St",
"line2": null,
"city": "Richmond",
"state": "VA",
"zip": "23224"
}
}
],
"eligibility": {
"applyTypes": [],
"otbProducts": {
"loanOptions": [],
"leaseOptions": []
},
"isEligible": false,
"isLoanEligible": false,
"isLeaseEligible": false,
"application": {
"lease": null,
"loan": {
"id": 2014942,
"isOtb": false,
"summary": null,
"status": "approved",
"options": [
{
"productID": 7,
"deferredInterestPeriod": 0,
"lineAmount": 10000,
"merchantDiscountRate": "0.00",
"minimumSpend": 300,
"rate": "32.99",
"termLength": 36
}
]
},
"customer": customer
}
},
"customerSearchErrors": []
}
}
}
In this scenario, our API has recognized the applicant as a returning customer with an application in progress and has added the returned applicationID to the orderID sent in the query input. You should make note of the loan or lease application id as you will need them in subsequent steps.
If loan is not null you can skip to Loan Approval & Checkout page. If lease is not null , you can skip to Lease Approval & Checkout (B&M) page or Lease Approval & Checkout (Ecomm) page depending on your integration type .
Customer With Open Line
A customer with an open line is a Koalafi customer who has access to open financing line.
An applicant who is eligible for an open line application will have options returned in the otbProducts field and the applyType field will have leaseOTB or loanOTB returned as the first value.
A customer who is OTB eligible will have a response that looks like the following:
{
"data": {
"customer": {
"customers": [
{
"id": 6847,
"firstName": "Wally",
"lastName": "Koala",
"cellPhone": "5555555555",
"emailAddress": "[email protected]",
"tokenizedTaxId": "4b417418-f6e7-4dca-9919-55ae404de9f0",
"birthDate": "1999-01-01",
"billingAddress": {
"line1": "424 Hull St",
"line2": null,
"city": "Richmond",
"state": "VA",
"zip": "23224"
}
}
],
"eligibility": {
"applyTypes": [
"leaseOTB"
],
"otbProducts": {
"loanOptions": [],
"leaseOptions": [
{
"leaseTerm": "12",
"approvedAmount": "3000.00",
"applicationFee": "",
"earlyBuyoutDiscount": "30.00",
"sacTerm": 0
}
]
},
"isEligible": true,
"isLoanEligible": true,
"isLeaseEligible": true,
"application": null
},
"customerSearchErrors": []
}
}
}
If the customer is an OTB customer, then you can use the information returned from the customer query to apply the applicant for financing using their open line. This saves them from filling out their application information again. If you choose to have the OTB customer skip completing the application again, then you should still display their contact information and have them verify that the information we have is up to date. If their contact information has changed, they should be allowed to update it prior to submitting their application.
Customer Ineligible for Financing
An ineligible response might look something like the following:
{
"errors": [
{
"message": "Applicant has an application in 'Accepted'. Not eligibile for new app at this time",
"path": [
"customer",
"eligibility"
]
}
],
"data": {
"customer": {
"customers": [
{
"id": 25038
}
],
"eligibility": null,
"customerSearchErrors": []
}
}
}
In this response an error is returned, the message says "Not eligible for a new app at this time" and eligibility is null.
it's also possible that the response for an ineligible customer might look like:
{
"data": {
"customer": {
"customers": [
{
"id": 6847,
"firstName": "Wally",
"lastName": "Koala",
"cellPhone": "5555555555",
"emailAddress": "[email protected]",
"tokenizedTaxId": "4b417418-f6e7-4dca-9919-55ae404de9f0",
"birthDate": "1999-01-01",
"billingAddress": {
"line1": "424 Hull St",
"line2": null,
"city": "Richmond",
"state": "VA",
"zip": "23224"
}
}
],
"eligibility": {
"applyTypes": [],
"isEligible": false,
"isLoanEligible": false,
"isLeaseEligible": false,
"application": null
},
"customerSearchErrors": []
}
}
}
In this response errors is not returned but eligibility is. Within eligibility isEligible is false and applyTypes is an empty list. That means that there are not any ways for the customer to apply. Customer is still returned because we have successfully found the existing Koalafi customer. If a customer is ineligible for financing then they cannot continue with the application.
Updated over 1 year ago