API – Creating a Customer

LoanPro's latest release now allows users to add APO/FPO/DPO addresses for military personnel stationed overseas. For more information, see our article on API – Addresses.

Introduction

This article covers the basics for creating a customer. Further details are covered in other articles.

Depending on the loan type, different fields will be required.

For all customer types, the PrimaryAddress and MailAddress properties are present, there are validations for the 4 required elements for a valid address: country, state, city and address1.

For Flooring Customers, the creditLimit property is present.

For Flooring Customers and Companies, customerIdType, contactName, companyName properties are present.

Creating a Customer

To create a customer, a POST request is sent to this endpoint:

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

The data must be sent over in a POST request with a Content-Type of “application/json”. Below is an example of a request header.

Authorization: Bearer API_TOKEN
Autopal-Instance-ID: INSTANCE_ID
Access-Control-Allow-Origin: *
Content-Type: application/json

Request Body

The request body has the following fields:

  • status – The status of the customer (options determined by tenant settings)
  • customId –  A custom id to identify the customer
  • customerType – The type of customer (see API Customer Collections for more details)
  • customerIdType – The type of government ID number for a customer (see API Customer Collections)
  • gender – The gender of the customer (see API Customer Collections)
  • generation code – The Generation Code of the customer (see API Customer Collections)
  • References – This object includes a name, relation, and contact info for each reference (see API – Customer References)
  • Phones – This object contains the customer's phone information (see API – Customer Phones)
  • PrimaryAddress – The customer's primary address (see API – Addresses)
  • CreditScore – This object contains the customer's credit scores from Equifax, TransUnion, and Experian. These values are integers, not strings, so they don't need quotation marks around them.
  • MailAddress – The customer's mailing address (see API – Addresses)
  • CustomFieldValues – This object contains any custom fields that you've added to your customers (see API – Custom Fields)
  • __ignorewarnings – Sometimes, you'll get an error response warning that something is wrong, like the phone number or address being used on another customer. Because these warnings are in place to prevent fraud, we recommend you double-check your data first, but marking "__ignorewarnings" as true will bypass the warnings and create the customer regardless (see API – Customer Transaction Warnings)
  • birthDate – The customer's birthdate. YYYY-MM-DD
  • firstName – The first name of the customer
  • middleName – The middle name of the customer
  • lastName – The last name of the customer
  • ssn – The Social Security Number of the customer (take care to not reveal this number to unauthorized parties)
  • driverLicense – The driver license number of the customer
  • accessUserName – The username for the customer to use to access the customer website
  • email – The customer’s email address
  • Employer – This object contains information on the customer's employer, like contact info, hire date, and payment frequency.
  • driverLicense – The driver license number of the customer
  • companyName – Company name of the customer (if customer is a company)
  • contactName – The name of the contact at the company (if customer is a company)
  • customerId – The government ID number for a customer
  • creditLimit – The credit limit of a customer (if customer type is flooring)
  • accessUserName – The username for the customer to use to access the customer website
  • accessPassword – The password for the customer to use to access the customer website
  • ofacMatch – Whether or not the customer matches any individual from the OFAC specially designated nationals list
  • ofacTested – Whether or not the customer has been tested for OFAC compliance

Sample Payloads

Here's a sample payload body for an individual customer:

   {
"status": "Active",
"customerType": "customer.type.individual",
"customerIdType": "customer.idType.ssn",
"gender": "customer.gender.male",
"generationCode": "customer.generationCode.none",
"References": {
"results": [
{
"name": "John Doe",
"relation": "customerReference.relation.father",
"Address": {
"country": "company.country.usa",
"address1": "123 Theology St",
"zipcode": "45402",
"city": "Dayton",
"state": "geo.state.OH"
},
"primaryPhone": "2024456655",
"secondaryPhone": ""

}
]
},
"Phones": {
"results": [
{
"__ignoreWarnings": true,
"phone": "6514737969",
"isPrimary": "1",
"isSecondary": "0",
"delete": false,
"_index": 0,
"type": "customer.phoneType.cell",
"__isDirty": false,
"carrierVerified": 1,
"__lookupInProgress": true,
"carrierName": "",
"isLandLine": 0

}
]
},
"PrimaryAddress": {
"__ignoreWarnings": true,
"country": "company.country.usa",
"address1": "1401 NATIONAL PARK DR",
"zipcode": "279549451",
"city": "MANTEO",
"state": "geo.state.NC",
"geoLat": "36.0266693",
"geoLon": "-75.6704825",
"verify": false

},
"CreditScore": {
"equifaxScore": 711,
"transunionScore": 692,
"experianScore": 698
},
"MailAddress": {
"__ignoreWarnings": true,
"country": "company.country.usa",
"address1": "1401 NATIONAL PARK DR",
"zipcode": "279549451",
"city": "MANTEO",
"state": "geo.state.NC",

"geoLat": "36.0266693",
"geoLon": "-75.6704825",
"verify": false
},
"CustomFieldValues": {},
"__ignoreWarnings": true,
"birthDate": "1967-06-15",
"firstName": "John",
"middleName": "J",
"lastName": "Dow",
"ssn": "062617853",
"driverLicense": "0987514228124",

"accessUserName": "oKUnKw7bNQk9VAV9qIU6",
"email": "KittyHawk78729649@wrightbros.com",
"Employer": {
"phone": "",
"payDate": "2021-07-09",
"Address": {
"__ignoreWarnings": true,
"country": "company.country.usa",
"address1": "1401 NATIONAL PARK DR",
"zipcode": "27954-9451",
"city": "MANTEO",
"state": "geo.state.NC"
},
"hireDate": "2021-08-03",
"incomeFrequency": "customerEmployer.incomeFrequency.annually",
"payDateFrequency": "customerEmployer.payDateFrequency.monthly",
"income": "3344.12",
"companyName": "Wright Cycle Company",
"title": "Owner / Operator"

}
}

Here's a sample payload for a company customer type:

{
"status": "Active",
"customerType": "customer.type.company",
"customerIdType": "customer.idType.employerNumber",
"gender": "customer.gender.male",
"generationCode": "customer.generationCode.none",
"saleTransferPii": 1,
"PrimaryAddress": {
"country": "company.country.usa",
"state": "geo.state.NJ",
"address1": "188 Generic Lane",
"zipcode": "11111",
"city": "Newbridge"
},
"MailAddress": {
"country": "company.country.usa",
"state": "geo.state.NJ",
"city": "Newbridge",
"address1": "188 Generic Lane",
"zipcode": "11111"

},
"CustomFieldValues": {
"results": []
},
"accessUserName": "",
"companyName": "Stackswell & Co.",
"contactName": "Thomas Oscar",
"customerId": "951547512",
"email": "cat@cat.cat"
}

And here's a sample for a flooring loan:

{
"status": "Active",
"customerType": "customer.type.flooringCustomer",
"customerIdType": "customer.idType.employerNumber",
"gender": "customer.gender.male",
"generationCode": "customer.generationCode.none",
"saleTransferPii": 1,
"PrimaryAddress": {
"country": "company.country.usa",
"state": "geo.state.AK",
"address1": "654 N 234 S",
"zipcode": "90125",
"city": "Sloop City"
},
"MailAddress": {
"country": "company.country.usa",
"state": "geo.state.AK",
"city": "Sloop City",

"address1": "654 N 234 S",
"zipcode": "90125"
},
"CustomFieldValues": {
"results": []
},
"accessUserName": "",
"firstName": "123",
"creditLimit": "90000.00",
"companyName": "Flooring Unlimited",
"contactName": "Fred Floorby",
"customerId": "987654651"

}

Q&A

Question:

What is the minimum data necessary to create a customer?  For example, we receive a TransactionWarningException/409 if we submit a phone number that already exists or an email with a suspect address, so can we create a customer without a phone number or email?

Answer:

Technically, an individual user can be created with nothing more than a first name, last name, primary address, and mailing address:

{
"firstName":"John",
"lastName":"Dow",
"PrimaryAddress":{
"__ignoreWarnings":true,
"country":"company.country.usa",
"address1":"1401 NATIONAL PARK DR",
"zipcode":"279549451",
"city":"MANTEO",
"state":"geo.state.NC",
"geoLat":"36.0266693",
"geoLon":"-75.6704825",

"verify":true
},
"MailAddress":{
"__ignoreWarnings":true,
"country":"company.country.usa",
"address1":"1401 NATIONAL PARK DR",
"zipcode":"279549451",
"city":"MANTEO",
"state":"geo.state.NC",
"geoLat":"36.0266693",
"geoLon":"-75.6704825",
"verify":true
}
}

We do not recommend this, however. It is recommended that you have at least a phone number, primary address, mailing address, SSN/SIN, date of birth, and gender for each customer. Many settings for a customer will be drawn from your defaults and customer settings, if not specified in the payload.

Question:

Our understanding is that customer creation occurs despite transactional warnings.  Can you confirm this is correct, and can you list the fields that will throw TransactionWarningExceptions upon duplication with other customer records?  It’s also easy enough for us to reverse the customer-creation logic, but if we wanted to, could we configure so that customer creation does not occur if there are transactional warnings?

Answer:

Customer creation will not occur if a transactional warning is received. You can choose to bypass transactional warnings by including the following in your payload:

"__ignoreWarnings": true

If duplicate or incorrect data is entered, these items will trigger a transactional warning:

  • Social Security/Social Insurance Number (if SSN is included, it must be 9 numeric characters long)
  • Email Address
  • Phone Number
  • Primary Address
  • Mailing Address

The API – Customer Transaction Warnings article gives more information about these warnings and how to correct the problems they indicate.

What is StackBlitz?
Many of our article 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.


How did we do?


Powered by HelpDocs (opens in a new tab)