Contacts API - quandis/qbo3-Documentation GitHub Wiki

The Contact module provides a place to gather and store contact information about all the relevant entities surrounding your business.

Classes

Class Description
Contact Used to track an individual and/or address. Includes latitude and longitude for geocoding purposes.
ContactMethod Stored email, phone, fax, website, instant message or other methods of communicating with a contact. Child of Contact.
ContactTemplate Template table optionally used to classify contacts. Offers ability to secure access to contacts by limiting what contact templates a user has access to.
Organization Used to track a company. Derives from Contact, so every Organization has Contact fields as well.
Court Tracks courts (federal, state or county).
Geography Defines geographic regions that apply to a parent entity. For example, define the country, state, city, zip code or geographic radius that an Organization is qualified to perform work in.
ProfessionalLicense Stores licensing information associated with a contact, such as driver's license, passport, attorney bar numbers, real estate broker license, etc.
State Drive drop down lists of US states.
Collection Represents a 'label' that can be applied to any object.
CollectionMember Maps an object to a Collection, indicating membership in the collection. For example, a Person may be labeled as part of a Document Prep team and a Call Center operator team.
CollectionTemplate Template table optionally used to classify collections. Offers ability to secure access to collections by limiting what collection templates a user has access to.

Contact Templates

In most uses cases, power users can classify Contacts using either ContactType or tags (see below). However, there are three use cases where one should consider creating a ContactTemplate, and populating this field when creating Contacts:

  • If you need to restrict access to certain Contact records based on role (e.g. only allow the Accounting role see Contacts mapped to a 'Billing Contact' template)
  • If you wish to automatically geocode some contacts but not others
  • If you wish to automatically link contacts by social security number

Phones and Emails: Contact Methods

Rather than storing HomePhone, WorkPhone, CellPhone, Fax, WorkEmail, HomeEmail, Website, LinkedInProfile and such in the Contact table, the ContactMethod class is used instead. This allows for an extensible, unlimited number of phone numbers, emails, and such to be associated with a Contact.

From Design > Configuration > Modules > ContactMethod, you can create new Types such as "Phone", "Email", "WorkPhone", etc. Creating these types will:

  • populate the ContactMethodType dropdown list, and
  • extend Contact/Save to handle the type as a field

For example, if you have no Contact Method Types defined, the following call will ignore Email:

Contact/Save?FirstName=John&LastName=Doe&[email protected]

If you have created a Contact Method Type called Email, the same REST call will populate a ContactMethod row with ContactType = 'Email' and Value = '[email protected]'.

If you create ContactMethod Types for Fax, HomePhone, and Website, you can then call:

Contact/Save?FirstName=John&LastName=Doe&[email protected]&Fax=800.555.1212&HomePhone=800.555.2323&Website=www.google.com

Labels (aka Tagging, Collections)

The Contact module includes classes that support 'labels', which is the ability to tag or categorize records with an unlimited number of attributes. Labels examples include:

  • Title Companies: a group of Organizations that perform title work
  • Foreclosure Attorneys: a group of Organizations that manage foreclosures
  • Team: a group of users representing a team
  • High Risk Loans: a group of loans that are considered high risk
  • Preferred Brokers: a group of real estate brokers that are preferred by a client

Most QBO classes include a {Class}Type property (e.g. Loan.LoanType, Organization.OrganizationType, Contact.ContactType), any given record may have only one type defined. However, any QBO record may have an unlimited number of labels applied to it. This structure was born when early QBO clients attempted to classify Organization.OrganizationType as 'Title Company', 'Field Services Company', and 'Recording Company', only to realize that many companies can be all three. Rather than creating three Organization rows, a single 'Big Vendor' Organization row may have three tags: 'Title', 'Field Services', and 'Recording'. When a search is performed, the following will produce a list of Field Services companies:

Organization.ashx/Search?Tag=Field Services

Most QBO search panels support the ability to select multiple records and 'label' them with an existing or new label. This action creates a Collection (if the label is new), and a CollectionMember row for each selected item mapping it to a Collection.

Geocoding

Geocoding refers to enhancing an address with additional information, typically latitude and longitude. This serves two common QBO use cases: calculating distance between entities, and correcting (or normalizing) an address. Geocoding is invoked by calling:

  • Contact/Geocode?Address=X&PostalCode=Y,
  • Contact/Geocode?Address=X&City=Y&State=Z, or
  • Contact/Geocode?Address=X&City=Y&State=Z&PostalCode=A

Calling Contact/Geocode is an excellent unit test for a power user, and a useful API for third party systems, but it does not change or save any data in the QBO database. To persist the results of a geocode, call Contact/Normalize which will call Contact/Geocode, and save the results if the confidence returned is high enough.

-- Create a Contact for us to play with
Contact/Save?Address=X&City=Y 
-- Assume this returns a ContactID=27
Contact/Normalize?ID=27

Note: Normalize will overwrite the Address, City, State, PostalCode, Country, Latitude, Longitude, VerifiedSource, VerifiedDate and VerifiedConfidence fields in the Contact table.

Note: any class that inherits from Contact, such as Organization and Broker, implement the Geocode and Normalize methods.

Geocoding Mechanics

QBO has built-in mapping providers that perform geocoding for United States, including Google, Bing, and Smarty Streets. When calling Contact/Geocode, the following logic is applied:

for each mapping provider configured in the QBO installation
  invoke the provider's geocode API
  calculate the confidence that the result matches the input
  if the confidence > minimum confidence required (80, by default), stop

Note that a given mapping provider (Google, for instance) may return more than 1 address for a given input. Contact/Geocode will return all results sorted by confidence descending, including the calculated confidence for each result.

Optional parameters include:

  • Confidence: this will override the default minimum confidence expected; e.g. Contact/Geocode?...&Confidence=0 will simply return the first hit, regardless of confidence level
  • Provider: if specified, only that provider will be used; e.g. Contact/Geocode?...&Provider=Bing will only call Bing's geocoding API

Geocode Confidence

If a geocodeed address confidence is returns a value of 80 or more, it is considered a 'good' match. Confidence is calculate by comparing the input address to the output address. Specifically:

  • Start with an assumed confidence of 100
  • If the postal codes don't match, reduce the confidence by 20
  • If the states don't match, reduce the confidence by 50
  • If the cities don't match, reduce the confidence by 10
  • If the house numbers don't match, reduce the confidence by 20
  • If the street names don't match, reduce the confidence by 5
  • If the street types (Rd. vs. St. vs Pkwy) don't match, reduce the confidence by 3
  • If the full addresses don't match, reduce the confidence by 1

All of these thresholds are configurable from Design > Configuration > Contact > Settings.

Google Maps API Configuration

There are several configuration setting specific to the qbo.Google.Maps class used to do Google Maps-based geocoding, each in the qbo.Google.Properties.Settings configuration section:

  • GeocodeUrl: URL to call for geocoding; can include channel parameters
  • GeocodeUrlPremier: URL for accessing with a client parameter
  • GeocodeUrlRestricted: URL for accessing with a key parameter
  • ApiKey: used with the Premier URL
  • RegstrictedKey: used with the Restricted URL
  • JSVarGoogleMapsKey: passed to the QBO javascript used for browser-based map rendering
  • Signature: signing key used for server-side geocoding requests

To override any of these settings, created a SystemDefault like: qbo.Google.Properties.Settings.{Setting}

Telephony

The Contact modules includes an ITelephony interface to facilitate call center integration. The interface includes:

  • CallOutbound: initiates an outbound call, typically by clicking on a phone number link on a web page
  • CallInbound: called by call center software to trigger rendering of a configuration-drive web page
  • Transfer: initiates a call transfer
  • Login: tells call center software that an agent is logged in
  • Logout: tells the call center software that an agent is logged out
  • Pause: tells the call center software to stop routing calls to an agent temporarily
  • Resume: tells the telephony server to resume routing calls to an agent
  • Validate: verifies a phone number

Quandis has a pre-built plugin to integrate FiveNine.