API – Creating a Customer

General

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

Note: There is a validation that requires the mailing address to be present when creating a customer. The following things will be validated:

For all customer types:

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:

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 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:

  • customId –  A custom id to identify the customer
  • customerType – The type of customer (see API Customer Collections for more details)
  • status – The status of the customer (options determined by tenant settings)
  • firstName – The first name of the customer
  • lastName – The last name of the customer
  • middleName – The middle name of the customer
  • birthDate – The birthday of the customer
  • gender – The gender of the customer (see API Customer Collections)
  • generation code – The Generation Code of the customer (see API Customer Collections)
  • email – The customer’s email address
  • 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
  • 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)
  • customerIdType – The type of government ID number for a customer (see API Customer Collections)
  • 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

Below is a sample body for an individual payload:

{
"status": "Active",
"customerType": "customer.type.individual",
"customerIdType": "customer.idType.ssn",
"gender": "customer.gender.male",
"generationCode": "customer.generationCode.none",
"Phones": {
"results": [
{
"__ignoreWarnings": true,
"phone": "2524732111",
"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": true
},
"CreditScore": {
"equifaxScore": 610,
"transunionScore": 634,
"experianScore": 590
},
"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
},
"CustomFieldValues": {},
"__ignoreWarnings": true,
"birthDate": "1871-08-14",
"firstName": "Orville",
"middleName": "",
"lastName": "Wright",
"ssn": "120175200",
"driverLicense": "C606346",
"accessUserName": "FirstInFlight2",
"email": "firstinflight@wrightbros.com",
"References": {
"results": [
{
"name": "Susan Koerner",
"relation": "customerReference.relation.mother",
"Address": {
"country": "company.country.usa",
"address1": "123 Theology St",
"zipcode": "45402",
"city": "Dayton",
"state": "geo.state.OH"
},
"primaryPhone": "7445654561",
"secondaryPhone": ""
}
]
},
"Employer": {
"phone": "3945191400",
"payDate": "2017-10-13",
"Address": {
"__ignoreWarnings": true,
"country": "company.country.usa",
"address1": "1401 NATIONAL PARK DR",
"zipcode": "27954-9451",
"city": "MANTEO",
"state": "geo.state.NC"
},
"hireDate": "1886-03-10",
"incomeFrequency": "customerEmployer.incomeFrequency.annually",
"payDateFrequency": "customerEmployer.payDateFrequency.biWeekly",
"income": "2950.00",
"companyName": "Wright Printing Offices & Shop",
"title": "Owner / Operator"
}
}

Q&A

Question:

What is the minimum data necessary to create a customer?  E.g., we receive a TransactionWarningException/409 if we submit a phone number that already exists or an email with a suspect address, but we can create 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: "__ignoreWarnings": true

In your payload.

The items that will trigger a transactional warning are:

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

This article will give more information about transactional warnings: API – Customer Transaction Warnings


How did we do?


Powered by HelpDocs (opens in a new tab)