How to Use the Mortgage Home Loan Comparison API

Our first comparison engine dates back to around 2006 when the feature effectively occupied the front page of my iChoice website. It later become a backend feature, and since I left the business it's a tool that we've only made available to our former Platinum clients. An article titled "Website Mortgage Comparison Engine" details how the feature integrates with Yabber and how it functions on our mortgage broker website. Future articles will discuss our industry-leading and industry-first equipment and auto products/widgets (now used by over 1000 businesses), and another article details how our Property API and associated website features integrate with the Comparison API we're about to discuss.

API Documentation: The information described on this page is extremely limited, but it provides sufficient information to generate accurate results. More extensive and formal documentation will be introduced at some point in the future.

This article details the actively supported Version 2 of the API, while our most recent release is Version 4. The latter two integrate AI Policy resolution in seriously significant ways, and the responses to Version 4 are generated entirely with AI. While many claim to have AI-powered widgets and tools, we'd argue that their use of the term is insulting to those that actually know how to use it.

API Version 4+: To use AI versions of this API, ensure your API Key has sufficient privileges and include the version in the API requests detailed below.

Version 2 of the Comparison API (so, this version) was released to the industry as an open sourced tool around 5-years ago, and the product was given away freely with data dumps every three days so those in the marketing space could add validify to the non-compliant forms they're using on their website to qualify mortgage candidates originating from Facebook. Their wayward "Congratulations, You're Qualified" messages are illegal, so we through we'd give them the tools necessary to formulate a compliant and ethical response. Needless to say, nobody used it.

Why The Comparison Engine Wasn't Included in the Website Earlier?: We've had this article in draft since 2019 (albeit, it's changed since then), and we've considered including the feature with each and every plugin update. However, with each new feature - and the website feature is extensive because it integrates heavily with forms and reporting - it creates a massive support burden on our end, and we're in a far better position to support how users apply the product now than we were in the last year or so.

Facebook Advertising: We haven't run a single Facebook campaign in the last five-or-so years without integrating this comparison engine in some way, and every stepped form has required the inclusion of product details and immediate results before any details are provided (more on this vital compliance obligation another time). There's a dozen reasons why our Facebook campaigns consistently and significantly outperform others in the market, and it's the integration of the tool we're about to discuss that contributes to our success.

We're Not Driven by Rate

The terms 'rate-chasers' is thrown around liberally without an understanding that 94% of all consumers consider rate to be the single most important attribute in a home loan, so virtually all borrowers consider rate more important than anything else until educated otherwise. We're not 'rate=chasers' ourselves, and I was never focused on rate as a broker, but we understand the part their play in marketing and your online and offline funnels. Having a comparison tool on your website simply keeps borrowers on your website and keeps them off other similar services. Remember, it's important that we speak in a language that the consumer understands, and we need to provide tools that'll maintain relevance and keep users engaged; it's time for the industry to let go of the flawed definition often applied to 'rate chasers', or at least understand the vital part rates play in shaping an opinion of you, your business, and your expertise.

Those of our clients that have used the website comparison engine have seen outstanding results.

Comparison API Availability

All our clients have an API Key, and that key currently accesses the Comparison (and most other) resources. If you're not an active client of any type and would like access to the API, give us a call. A free basic plugin is available for WordPress, but you'll have to be in our Finance Marketing Facebook Group to gain access to the link.

Equipment and Auto Comparisons: The equipment endpoint provides access to the most comprehensive and complete equipment comparison engine in the market, and it's the endpoint that has seen most usage in the last 5 years. True AI functionality is integrated into the API by default, and we supply the only true AI widgets in the industry. As a long-used tool, inclusion of this standalone product is a simple plug-and-play solution with public features activated in a few seconds. If you have access to the documentation, please feel free to use the product in any manner that floats your boat.

Comparison API Features

The RESTful API returns data in a manner that you'd expect. You supply certain URL parameters in a $_GET request and data is returned as standard JSON. Various filtering options apply via standard URL parameters (all introduced shortly). The API itself supports around 60 'actions', but we're going to introduce just three: comparison, product, and helper. Other 'action' requests return data filtered in various ways, but our standard 'Lender Product API' is most often used for general purposes (such as our Product Widgets).

Comparison API Endpoint and URL Parameters

The Comparison API is accessed via a dedicated comparison/{action}/api.json endpoint. In order to supply the appropriate values into the request you'll have to access that endpoint with the helper action (comparison/helper/api.json), or refer back to documentation. Only those URL parameters with a value need to be supplied.

API URL Parameters

apikey

The API requires an API Key. If invalid an error response will be returned. Multiple erroneous requests results in the originating IP address to be permanently banned.

action

The action parameter is used to indicate what data you would like returned. An action is always required. Those actions detailed in this article are comparison for the Comparison Engine, product for product-specific data, and helper which retrieves all the available search parameters.

 ● 

product_category

If a product_category is supplied, it must be a single value. Multiple values will cause an error. If omitted the value defaults to 1 (Residential Mortgages).

1. Residential Mortgages
2. Margin Loans
3. Business Loans
4. Credit and Charge Cards
5. Leases
6. Overdrafts
7. Personal Loans
8. Regulated Trust Accounts
9. Term Deposits
10. Trade Finance
11. Transaction and Savings Accounts
12. Travel Cards

A single numeric value should be used, so product_category=1 for Residential Mortgages or product_category=3 for Business Loans.

lvr

The lVR may be supplied as either 50 or 0.5 (latter is preferred). The default value is 0.5 in order to retrieve all results.

loan_type

Available loan types are as follows:

1. Owner Occupied
2. Investment

If no values are supplied all results are returned. To limit to just Owner Occupied products, use loan_type=2. You can supply both values if required in a comma-separated string, such as loan_type=1,2. Values are ignored if provided but not required based on the product_category.

repayment_type

Available repayment types are as follows:

1. Principal and Interest
2. Interest Only

If no values are supplied all results are returned. To limit to just P&I products, use repayment_type=1. You may supply both values if required in a comma-separated string, such as repayment_type=1,2. Values are ignored if provided but not required based on the product_category.

rate_types

Available rate types are as follows:

1. Principal and Interest
2. Variable
3. Fixed
4. Bundle Discounted Fixed
5. Bundle Discounted Variable
6. Cash Advance
7. Discount
8. Market Linked
9. Penalty
10. Purchase

Most common for residential searches are 1 (Variable) and 2 (Fixed), and to a lesser extent, 6 (Discount) and 7 (Introductory). If no values are supplied, Variable and Fixed (1,2) products are returned. To limit to custom loan types, use a comma separated string such as rate_types=1,2,7. Values are ignored if provided but not required.

feature_ids

Available Feature IDs are as follows:

1. Offset Account
2. Redraw Facility
3. Extra Repayments
4. Digital Banking
5. Unlimited Transactions
6. Fraud Protection
7. Guarantor Loan
8. Other Feature
9. Loyalty Program
10. Relationship Management
11. Bill Payment Facilities
12. Access to Credit Cards
13. Digital Wallet
14. Notifications
15. New Payments Platform (Real-Time Payments)
16. New Payments Platform (Payments Via PayID)
17. Balance Transfers
18. Overdraft Facilities
19. Allows Additional Cards
20. Free Transactions
21. Interest Free
22. Interest Free Transfers
23. Insurance
24. Cashback Offer
25. Instalment Plan
26. Bonus Rewards
27. Complimentary Product Discounts
28. Free Transaction Allowance
29. Donate Interest

All products with any product features are returned by default. To limit results to those with specific product features, use a comma separated string such as rate_types=1,2,7,9,11,13 etc. Values are ignored if provided but not required.

require_all_features

To limit returned results returned with the feature_ids with only those features that match all features, use the parameter of require_all_features=1.

lenders

All lenders are queried by default. For Yabber users, only those default lenders listed via your website profile are queried (if querying outside of your website you should provide your site_id or all records are returned). All lenders have an associated 3-letter code (returned in the helper response), so to query a limited set of lenders you should use lenders=cba,anz,nab etc.

per_page and page_id

Results are paginated with 30 records per page by default. To query the next page, use page_id=2 etc, and to alter the number of results per page, use per_page=30. For most users, the page is limited to 30 results but this may be altered by clients in Yabber.

order_by

You may order returned results on interest rate (default) or comparison rate. To order_by on comparison rate, use order_by=comparison_rate.

 ● 

purchase_or_refinance

The 'purchase' or 'refinance' option is optionally used, but required when you would like to return custom repayment options in the response (and graphs). Values are purchase (default) and refinance. The purchase_or_refinance=refinance option returns savings made over various loan terms, and the reduction in years if current repayments are continued with the new lower rate.

property_value, property_remaining, property_years, and property_rate

These values are required if you wish to return custom repayment calculations to the user (measured on $500k by default). The values are self-explanatory; the property value, remaining balance, years left (optional), and current rate. If these values are all provided we'll also return links to various comparative graphs (linked via modal in the engine). A feature introduced in Version 4 of the API returns the JSON necessary to render a JavaScript graph and it's expected that we'll migrate this feature into the V2 API since it's seeing increase client usage. If values are provided (and valid) the LVR is determined from these values.

extra_repayments, loan_amount, and frequency

the extra_repayments, loan_amount, and frequency are applied in those cases where they're required for graphing or comparison analysis. If no values are provided we'll default to standard values for the purpose of illustrating a payment schedule. Valid values for frequency are 'w' (week), 'f' (fortnight), and 'm' (month).

loan_amount_compare, loan_amount_compare_rate, and loan_amount_compare_years

Thee attributes are applied when coming off the tail end of a lead form or similar, and results are required for comparative purposes. Normally used with purchase_or_refinance=refinance (as detailed above), graphing links are created to details where and how savings are made. These values are not required for standard comparison queries. Not unlike the standard extra_repayments, loan_amount, and frequency parameters, the 'compare' values are generalised for the purpose of illustrating the impact of extra repayments etc.

graphing

Graphing is normally used when retrieving a single value via the product action. Using grpahing=1 returns a significant quantify of JSON values that are used for the purpose of turnkey graphing with various JavaScript tools.

 ● 

site_id

If using the API outside of your website environment, use site_id={32-character-string} in order to limit results to those lenders as defined in Yabber.

bmuid

The BMUID is the BM User ID - a unique identifier for each user that visits your website. It is not required outside of your website but may be optionally applied. If the ID doesn't match a known user it is discarded.

 ● 

General Filters

You may use the following list of filters in your query URL to limit results to products matching specific features. Not all filters are applied to all product types so exercise care when used. More common filters are is_guarantor, is_smsf, is_construction, and cashback (the latter returning products that have a known cashback offer).

• is_guarantor
• is_tailored
• is_smsf
• is_auto
• is_business
• is_construction
• is_equipment
• is_green
• is_lease
• is_secured
• is_unsecured
• cashback

Filters are ignored unless applied, so to return Guarantor produces, use is_guarantor=1. When required, each of these flags are displayed in the website comparison engine.

policy

The policy attribute is applied on the V3/4 API, but it's worth mentioning. The base-64 URL-encoded parameter string is simple plain text describing your client requirements. It may be a set of circumstances or potentially limiting criteria - such as Visa or settlement requirements - and products are reordered based on suitability then returned with an additional field called policy that includes a large amount of AI-generated text describing lender-specific options and solutions.

Querying the API

A request to comparison/comparison/api.json (where the second comparison is the action) with no parameters returns all residential mortgage products listed on interest rate. The default LVR is 0.5 so includes virtually everything. It's only when parameters start to exclude, filter, or order products that the result starts to change shape.

Responses are returned as standard JSON. The returned package is quite large but extremely fast. It's not uncommon to show the lowest rate products alongside those that match queried criteria, and these products may be returned by the parameter of include_lowest in the request (the 8 lowest rate products are returned on a 'lowest' key in the response).

A Typical Response

We'll query the API and look at just the first result (I'm showing a common CBA product only because it populates with most data, but CBA rarely return in top results). No limiting criteria were applied via any URL parameter.

Note that the 'repayments' and 'repayments_savings' keys include basic data (the latter not showing anything because we didn't apply our own property values). It's these figures that are applied into our Property API for repayments on the listed property price. Rendering results to a page can take as little as a few lines of code - it's very easy, so if you don't use our own plugin you can probably hack it together yourself.

Images are available in our Lender Image Pack, and the easiest way of obtaining them is by downloading the plugin and just copying the 'images' folder. Each image is listed on the lender code, so Commonwealth Bank will reference {image-size}/cba.png.

Note that the standard response includes documents with a URL to the document on the lender website. We also include the local Yabber URL so - assuming you provide access to the download, and in company with a user BMUID - you're able to apply general triggers and tracking on document downloads. The images associated with each PDF record are normally returned with a snapshot of the front page of the PDF.

We'll provide a simple 10-line block of code for rendering results sometime soon.

Loancalc Graphs

The standard API response (via any product-related endpoint) includes 17 image graph links that are formatted to retrieve results based on the values provided in the query. A second link includes the URL to call the JSON with data used to build the image. It's the latter call that might prove useful for generating JavaScript graph alternatives, or for general display of the resolved information.

API Security: Never expose your API Key, so don't link to images directly. instead, copy them locally and given them a .png extension.

The Image Graph 'Loancalc' API is used by us to generate images that can be programmatically into auto-generated PDFs without any effort, and that remains their primary purpose. That said, with the increased usage of the API by clients we'll include various generic image graphs on website 'Lender Product Pages' soon.

All graphs with example images are returned in the helper response (detailed below). Available graphs are listed (again, they're images, so their purpose is not itended for dynamic website display).

• Loan Balance
• Principle Component of Repayment
• Interest Component of Repayment
• Cumulative Interest over Loan Term
• Principle & Interest Components of Repayments
• Principle & Interest Components of Repayments
• Extra Repayments Affect on Loan Term
• Repayments by Varying Loan Term and Interest Rate
• Cumulative Interest over Varying Term
• Loan Balance Comparison
• Loan Comparison Cumulative Interest
• Loan Comparison Interest Component
• Loan Comparison Balance
• Principle & Interest Amortisation Table
• Summary Principle & Interest Amortisation Table

There's a ton of graphing options, so we'll talk to you about what you need when you actually need it.

The Product Action

The product action returns only a single 'enhanced' result. The only required parameter is bmid (which is a Product ID, and not to be confused with the bmuid), and pricing information is optionally supplied in order to customise default graphing. The Product response includes a large number of JSON blocks that may be integrated directly with most popular graphing tools.

The Helper Action

The helper function simply provides a list or arrays that include the numeric values associated with various query options. Querying comparison/helper/api.json (with no parameters) returns the following (truncated for space and readability). You should query this endpoint and save the values locally if you're building a larger application yourself.

It['s the id value associated with each record that is used to filter results. The 'hash' value is one that should be recorded for use in other more advanced queries.

This page provides the parameters required for general usage.

Website Integration

The response includes related_blog, related_faq, and related_insights arrays. These are articles assigned to various lender groups or specific lenders - usually categorised by tier, lending purpose, or some other common attribute. Since the feature in Yabber has sat with the 'Reserved' menu item for so long it's likely you haven't seen it... but we'll flick the switch after some minor updates.

An apply_online link is included on a product or lender basis. Our FAQ module will detail how to assign appropriate values to the string so you can send the query off to an online application portal.

A links array is returned with the archive, product, and video keys, and it's the latter that is most important. The video you have assigned to the lender in Yabber is returned, and this is the video shown on the specific product/lender page. Outside of your website it's simply a valuable video asset.

Used on Your Website or a Standalone Comparison Website

Our standard mortgage broker website framework is now shipped with a full comparison engine that compares favourably against bug-name commercial products. An article titled "Website Mortgage Comparison Engine" details how the feature integrates with Yabber and how it functions on your website. For those that have ready this far, you can expect a plugin update shortly that'll introduce the feature.

A standalone comparison website is available and works on a fast-loading non-WordPress framework. We've had a bunch of these sites running for at least a couple of years with results measured in the billions, so it's a worthwhile consideration.

Updated Fact Find Reports and Lead Forms

All our 'stepped' conditional lead forms, fact find PDF reports, and other tools, will all be updated over the next few weeks to integrate the API. We've used dozens of stepped form variations over the last few years (which I hate, because I don't like the ridiculous notion of online qualification - more on this later), and all these battle-tested tools will be available via a plugin update. The same forms will obviously be available in modals.

Considerations

This API is heavily integrated with the pending public release of our Property API. Not unlike the Comparison API, we've delayed the Property API only because of the support burden that invariably follows. Given the closeness of the two features (repayment info is listed with property containers), it was necessary to release this product as a default website inclusion before any other.

We're testing the use of the comparison engine on partner websites as part of the partner plugin, and thus far it's worked quite well.... and it certainly adds significant value to your already leading product proposition.

Conclusion

Over the last few months, and certainly since the adoption of AI, we're seeing the inclusion of 'gamified' tools such as the Comparison Engine to be essential. Your digital footprint speaks volumes about your business and often usually helps a client shape their option based on how you demonstrate those essential UX (E-E-E-E-A-T) attributes.

I often hear coaches, industry 'leaders', and others, diminish the value of product information and rate data in the early attraction funnel, and they're absolutely and objectively wrong. Their wayward messaging is shaped by antiquated ideologies originating from titanic-era lack of technology. With over a billion in volume generated via our systems each month, we can state categorically that the features we've described above are becoming an essential client-facing business tool, and they'll absolutely support conversions in far higher numbers.

Our website is still priced lower than competing products, and as the only Microsoft-integrated funnel-focused product in the market, it'll support more conversions and more business.