Skip to main content

Integration

Overview

For the first phase of integration between MyCRM and the Mortgage Recommendation Engine (MRE), it was decided to use the MRE's user interface for viewing results – instead of directly integrating the MRE API and rendering the results inside MyCRM's own UI. To support this approach, an API endpoint was provisioned that allows MyCRM to send the customer's lending scenario data to the MRE backend, from where it can then be loaded up into the MRE's UI and calculated.

Integration Process

The steps below summarise the MyCRM integration process:

  1. MyCRM sends data to the MRE's Create Session endpoint
  2. MRE stores the data as a "session" and returns the ID to MyCRM
  3. MyCRM loads the session in the MRE's user interface
  4. MRE calculates the lending scenario and displays the results

There is currently no automated integration of result data back to MyCRM; this is proposed for a future phase. The MRE UI does however include an Export PDF feature for manual saving of result data.

API

Server to server API

The MRE exposes a RESTful API which uses standard HTTP response codes, authentication, and verbs, and uses JSON payloads. The API is hosted on environment-specific domains:

Environment API Base URL
Test https://api.mre.test.blackfin.tools/
Production https://api.mre.blackfin.tools/

Authentication

The API uses the Bearer token authentication method. The HTTP Authorization Header must contain the following string:

Bearer <API_KEY>

Where <API_KEY> is replaced by the API key issued to you by BlackFin.

Endpoints

API endpoints are represented as paths appended to the base URL. Currently, only one endpoint is utilised by the MyCRM integration:

  • Create Session – this endpoint accepts data about an applicant's lending scenario / finances, and stores it as a "session" in the database. It returns a session_id that can be used to access the data within the MRE's UI.
    • Endpoint path: /sessions/create
    • Example URL: https://api.mre.test.blackfin.tools/sessions/create

The API also includes a Generate Report endpoint which performs the MRE calculations and returns the raw result data (JSON), however this is not currently used by MyCRM directly.

User Interface

The Mortgage Recommendation Engine UI can be accessed at the below addresses:

Environment Web URL
Test https://mre.test.blackfin.tools/
Production https://mre.blackfin.tools/

The MRE does not currently enforce any authentication to access the UI, however NZFSG have proposed restricting access in future if the URL does not contain a valid session_id (see below).


URL Params

The following query string parameters can be appended to the URL when access the user interface:

Back to top