MortgageRecEngine.MyCRM
Mortgage Recommendation Engine integration with MyCRM
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:
- MyCRM sends data to the MRE's Create Session endpoint
- MRE stores the data as a "session" and returns the ID to MyCRM
- MyCRM loads the session in the MRE's user interface
- 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_idthat 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
- Endpoint path:
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:
- session_id – Including this parameter on the end of the URL triggers the MRE to load and calculate the data from a previously created session. This is a key component of the MyCRM integration.
For examplehttps://mre.test.blackfin.tools/?session_id=BYWSw2DTUBuHVMW4ZdhK - lenders – Including this parameter of comma-separated lender codes instructs the MRE which lenders to calculate for when using the UI in "manual entry" mode (instead of pre-loading session data). This is optional.
For examplehttps://mre.test.blackfin.tools/?lenders=aia,asb,anz,bnz,westpac
API Reference
API Reference
Create Session
The Create Session endpoint accepts data about a customer's finances and lending scenario, which it stores in the database as a "session" and returns a SessionID parameter that can be used to load the data from that session in the Mortgage Recommendation Engine's UI.
Request
- Type:
POST - Path:
/sessions/create
Endpoint
The Create Session endpoint can be accessed from the following URLs:
| Environment | Endpoint URL |
| Test | https://api.mre.test.blackfin.tools/sessions/create |
| Production | https://api.mre.blackfin.tools/sessions/create |
Authentication
An API_Key is required to call this endpoint. HTTP Bearer Token authentication is used.
JSON Schema
The request payload is sent as HTTP JSON body using the following schema:
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Request JSON Payload",
"type": "object",
"properties": {
"Session": {
"type": "object",
"properties": {
"ExternalID": {
"type": "string",
"description": "External ID, for example a user ID to link the session to"
}
},
"required": [
"ExternalID"
]
},
"Details": {
"type": "object",
"description": "Main calculation details for mortgage calculation, see [CalculationDetails](https://docs.blackfin.tools/books/mortgagerecenginebackend/page/calculationdetails) schema"
},
"Lenders": {
"type": "array",
"description": "[Lender codes](https://docs.blackfin.tools/books/mortgagerecenginemycrm/page/lenders) to include in calculation. If no Lenders are passed (empty array), the calc will return ASB, ANZ, BNZ, AIA and Westpac by default",
"items": {
"type": "string",
"description": "",
"enum": [
"aia",
"anz",
"asb",
"bnz",
"co-op",
"kiwibank",
"liberty",
"sbs",
"tsb",
"westpac"
]
}
}
},
"required": [
"Details",
"Lenders"
]
}Examples
Example request payload:
JSON Request Body
{
"Session": {
"ExternalID": ""
},
"Details": {
"Loan": [
{
"LoanType": "New",
"Lender": null,
"LendingAction": null,
"LiabilityType": "HomeLoan",
"LoanAmount": 250000,
"TopUpAmount": null,
"TotalTermMonths": 180,
"InterestOnlyTermMonths": 180,
"Security": {
"Value": 300000,
"IsRBNZExempt": true,
"Location": null,
"PropertyType": [
"ResidentialProperty",
"FreeHoldResidential",
null
],
"SecurityType": "Proposed",
"UsageType": "OwnerOccupied"
},
"LoanId": 1
},
{
"LoanType": "Existing",
"Lender": null,
"LendingAction": "TopUp",
"LiabilityType": "HomeLoan",
"LoanAmount": 250000,
"TopUpAmount": 50000,
"TotalTermMonths": 183,
"InterestOnlyTermMonths": 219,
"Security": {
"Value": 300000,
"isRBNZExempt": false,
"Location": null,
"PropertyType": [
"ResidentialProperty",
"FreeHoldResidential",
null
],
"SecurityType": "Existing",
"UsageType": "OwnerOccupied"
},
"LoanId": 2
},
{
"LoanType": "Existing",
"Lender": null,
"LendingAction": "Refinance",
"LiabilityType": "HomeLoan",
"LoanAmount": 260000,
"TopUpAmount": null,
"TotalTermMonths": 180,
"InterestOnlyTermMonths": 216,
"Security": {
"Value": 300000,
"isRBNZExempt": false,
"Location": null,
"PropertyType": [
"ResidentialProperty",
"FreeHoldResidential",
null
],
"SecurityType": "Proposed",
"UsageType": "OwnerOccupied"
},
"LoanId": 3
},
{
"LoanType": "Existing",
"Lender": null,
"LendingAction": "Refinance",
"LiabilityType": "HomeLoan",
"LoanAmount": 370000,
"TopUpAmount": null,
"TotalTermMonths": 144,
"InterestOnlyTermMonths": 0,
"Security": {
"Value": 410000,
"isRBNZExempt": false,
"Location": null,
"PropertyType": [
null,
null,
null
],
"SecurityType": "Proposed",
"UsageType": null
},
"LoanId": 4
},
{
"LoanType": "Existing",
"Lender": null,
"LendingAction": "TopUp",
"LiabilityType": "HomeLoan",
"LoanAmount": 200000,
"TopUpAmount": 50000,
"TotalTermMonths": 180,
"InterestOnlyTermMonths": 0,
"Security": {
"Value": 210000,
"isRBNZExempt": false,
"Location": null,
"PropertyType": [
null,
null,
null
],
"SecurityType": "Proposed",
"UsageType": null
},
"LoanId": 5
}
],
"ApplicantParty": [
{
"Applicant": [
{
"ApplicantId": 1,
"Name": "Terence"
},
{
"ApplicantId": 2,
"Name": "Eve"
}
],
"Expense": [
{
"ApplicantId": 1,
"ExpenseType": "ChildCare",
"Frequency": "Monthly",
"Amount": 300
},
{
"ApplicantId": 1,
"ExpenseType": "ChildMaintenance",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "HigherEducationAndVocationalTraining",
"Frequency": "Monthly",
"Amount": 200
},
{
"ApplicantId": 1,
"ExpenseType": "OtherEducation",
"Frequency": "Monthly",
"Amount": 100
},
{
"ApplicantId": 1,
"ExpenseType": "PrivateSchoolCosts",
"Frequency": "Monthly",
"Amount": 300
},
{
"ApplicantId": 1,
"ExpenseType": "PublicSchoolCosts",
"Frequency": "Monthly",
"Amount": 150
},
{
"ApplicantId": 1,
"ExpenseType": "Groceries",
"Frequency": "Monthly",
"Amount": 200
},
{
"ApplicantId": 1,
"ExpenseType": "OtherGroceries",
"Frequency": "Monthly",
"Amount": 150
},
{
"ApplicantId": 1,
"ExpenseType": "BodyCorporatePrimaryResidence",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "CouncilRatesPrimaryResidence",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "ElectricityAndGasPrimaryResidence",
"Frequency": "Monthly",
"Amount": 100
},
{
"ApplicantId": 1,
"ExpenseType": "FurnishingsAndElectrical",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "HomeOperation",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "HomeRepairs",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "OtherPrimaryResidenceExpense",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "WaterAndSewerPrimaryResidence",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "BuildingInsurance",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "ContentsInsurance",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "HealthInsurance",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "IncomeProtection",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "LifeInsurance",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "OtherInsurance",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "VehicleInsurance",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "BodyCorporateInvestmentProperty",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "BuildingInsuranceInvestmentProperty",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "CouncilRatesInvestmentProperty",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "ElectricityAndGasInvestmentProperty",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "OtherInvestmentPropertyExpense",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "RepairsAndMaintenanceInvestmentProperty",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "RunningCostsInvestmentProperty",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "WaterAndSewerInvestmentProperty",
"Frequency": "Monthly",
"Amount": 200
},
{
"ApplicantId": 1,
"ExpenseType": "ContentsInsuranceSecondaryResidence",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "BodyCorporateSecondaryResidence",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "BuildingInsuranceSecondaryResidence",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "CouncilRatesSecondaryResidence",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "ElectricityAndGasSecondaryResidence",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "OtherSecondaryResidenceExpense",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "RepairsAndMaintenanceSecondaryResidence",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "RunningCostsSecondaryResidence",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "WaterAndSewerSecondaryResidence",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "MedicalAndHealth",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "NaturalTherapies",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "Board",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "DryCleaning",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "AlcoholTobacco",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "CinemaConcertsMemberships",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "GymSports",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "OtherRecreationalAndEntertainment",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "Pets",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "HomeMobilePhone",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "InternetPayTVAndMediaStreamingSubscriptions",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "PublicTransport",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "Registration",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "TaxiRideSharing",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "TollsParking",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "Kiwisaver",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "RegularDonations",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "VoluntarySaving",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "VoluntarySuper",
"Frequency": "Monthly",
"Amount": 10
}
],
"Income": [
{
"ApplicantId": 1,
"Frequency": "Yearly",
"Amount": 50000,
"AmountType": "Gross",
"IncomeType": "SalaryWages",
"Attributes": []
},
{
"ApplicantId": 1,
"Frequency": "Yearly",
"Amount": 5000,
"AmountType": "Gross",
"IncomeType": "RentalIncome",
"Attributes": [
{
"name": "PropertyBuildDate",
"value": "2018-11-06"
},
{
"name": "PropertyCountry",
"value": "NZ"
},
{
"name": "IsTaxExempt",
"value": true
},
{
"name": "SalePurchaseDate",
"value": "2019-11-11"
}
]
},
{
"ApplicantId": 2,
"Frequency": "Yearly",
"Amount": 40000,
"AmountType": "Gross",
"IncomeType": "SalaryWages",
"Attributes": []
},
{
"ApplicantId": 2,
"Frequency": "Yearly",
"Amount": 5000,
"AmountType": "Gross",
"IncomeType": "WorkAllowance",
"Attributes": []
},
{
"ApplicantId": 1,
"Frequency": "Yearly",
"Amount": 10000,
"AmountType": "Gross",
"IncomeType": "Bonus",
"Attributes": []
},
{
"ApplicantId": 1,
"Frequency": "Yearly",
"Amount": 4000,
"AmountType": "Gross",
"IncomeType": "BoarderIncome",
"Attributes": [
{
"name": "BoarderIncomeType",
"value": "AllInclusive"
}
]
},
{
"ApplicantId": 1,
"Frequency": "Yearly",
"Amount": 3000,
"AmountType": "Gross",
"IncomeType": "CarAllowance",
"Attributes": []
},
{
"ApplicantId": 1,
"Frequency": "Yearly",
"Amount": 5000,
"AmountType": "Gross",
"IncomeType": "FamilyAllowance",
"Attributes": []
}
],
"Liability": [
{
"ApplicantId": 1,
"LiabilityType": "HomeLoan",
"RepaymentAmount": 2000,
"RepaymentFrequency": "Monthly",
"Limit": 4000,
"Balance": 10000,
"InterestRate": 0.02,
"RepaymentType": "PrincipalInterest",
"StartDate": "2017-11-15",
"TotalTermMonths": 228,
"InterestOnlyTermMonths": 228,
"Lender": "Kiwibank",
"IsRevolvingCredit": true
},
{
"ApplicantId": 1,
"LiabilityType": "CreditCard",
"RepaymentAmount": null,
"RepaymentFrequency": null,
"Limit": 30000,
"Balance": null,
"InterestRate": null,
"RepaymentType": null,
"StartDate": null,
"TotalTermMonths": null,
"InterestOnlyTermMonths": null,
"Lender": null,
"IsRevolvingCredit": null
},
{
"ApplicantId": 1,
"LiabilityType": "PersonalLoan",
"RepaymentAmount": 2000,
"RepaymentFrequency": "Monthly",
"Limit": 4000,
"Balance": 30000,
"InterestRate": 0.02,
"RepaymentType": null,
"StartDate": "2019-11-07",
"TotalTermMonths": 220,
"InterestOnlyTermMonths": null,
"Lender": null,
"IsRevolvingCredit": true
},
{
"ApplicantId": 1,
"LiabilityType": "Other",
"RepaymentAmount": 200,
"RepaymentFrequency": "Monthly",
"Limit": 4000,
"Balance": 10000,
"InterestRate": 0.01,
"RepaymentType": null,
"StartDate": "2018-11-07",
"TotalTermMonths": 183,
"InterestOnlyTermMonths": null,
"Lender": "Kiwibank",
"IsRevolvingCredit": true
},
{
"ApplicantId": 1,
"LiabilityType": "HirePurchase",
"RepaymentAmount": 2000,
"RepaymentFrequency": "Monthly",
"Limit": null,
"Balance": 20000,
"InterestRate": null,
"RepaymentType": null,
"StartDate": null,
"TotalTermMonths": null,
"InterestOnlyTermMonths": null,
"Lender": null,
"IsRevolvingCredit": null
},
{
"ApplicantId": 1,
"LiabilityType": "Overdraft",
"RepaymentAmount": 2000,
"RepaymentFrequency": "Monthly",
"Limit": 4000,
"Balance": 20000,
"InterestRate": 0.02,
"RepaymentType": null,
"StartDate": null,
"TotalTermMonths": null,
"InterestOnlyTermMonths": null,
"Lender": null,
"IsRevolvingCredit": null
},
{
"LoanId": 2,
"Lender": null,
"Balance": 195000,
"Limit": 250000,
"InterestRate": 1,
"RepaymentAmount": 15000,
"RepaymentFrequency": "Monthly",
"RepaymentType": null,
"TotalTermMonths": 183,
"StartDate": null,
"IsRevolvingCredit": null,
"InterestOnlyTermMonths": 216,
"ApplicantId": 1,
"LiabilityType": "HomeLoan"
},
{
"Lender": null,
"Balance": 200000,
"Limit": 260000,
"InterestRate": 2,
"RepaymentAmount": 10000,
"RepaymentFrequency": "Monthly",
"RepaymentType": "PrincipalInterest",
"TotalTermMonths": 180,
"StartDate": null,
"IsRevolvingCredit": null,
"InterestOnlyTermMonths": 216,
"ApplicantId": 1,
"LiabilityType": "HomeLoan",
"LoanId": 3
}
],
"NumberOfDependents": 1,
"NumberOfVehicles": 1
}
]
},
"Lenders": []
}
Validation
The API performs basic validation on the structure of the request payload but does not impose strict rules based on what is required for generating a calculation. This means that a successfully created session does not guarantee the data is complete for actual calculation in the UI. Data is loaded on a best-effort basis in the UI and the user is required to address any missing items, as needed.
Response
Success
If the Create Session completes successfully:
JSON Body
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Response JSON Body",
"type": "object",
"properties": {
"SessionID": {
"type": "string",
"description": "20 characters in length, random generated alphanumeric string, mixed case",
"example": "BYWSw2DTUBuHVMW4ZdhK"
},
"SessionURL": {
"type": "string",
"description": "Fully constructed URL to load up the session in the matching environment MRE UI.",
"example": "https://mre.test.blackfin.tools/?session_id=BYWSw2DTUBuHVMW4ZdhK"
}
}
}Examples
200: Success
Success Response
{
"SessionID": "BYWSw2DTUBuHVMW4ZdhK",
"SessionURL": "https://mre.test.blackfin.tools/?session_id=BYWSw2DTUBuHVMW4ZdhK"
}Error
If errors are encountered during the Create Session operation:
JSON Body
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"description": "Error information",
"properties": {
"message": {
"type": "string",
"description": "Human readable error message"
},
"status": {
"type": "string",
"description": "Error code in uppercase letters and _ as space",
"enum": ["INVALID_ARGUMENT","DEADLINE_EXCEEDED","NOT_FOUND","ALREADY_EXISTS","PERMISSION_DENIED","RESOURCE_EXHAUSTED","FAILED_PRECONDITION","ABORTED","OUT_OF_RANGE","UNIMPLEMENTED","INTERNAL","UNAVAILABLE","DATA_LOSS","UNAUTHENTICATED"]
},
"details": {
"type": "object",
"description": "Additional error details",
"properties": {
"validation_errors": {
"type": "array",
"description": "Errors thrown when validating input data",
"items": {
"type": "object",
"properties": {
"path": {
"type": "array",
"description": "An array of property keys or array offsets, indicating where inside objects or arrays the instance was found.",
"items": {
"type": "string"
}
},
"property": {
"type": "string",
"description": "Describes the property path. Starts with `instance`, and is delimited with a dot (.)."
},
"message": {
"type": "string",
"description": "A human-readable message for debugging use. Provided in English and subject to change."
},
"schema": {
"type": "object",
"description": "The schema containing the keyword that failed",
"properties": {
"type": {
"type": "string"
},
"description": {
"type": "string"
}
},
"required": ["type"]
},
"instance": {
"description": "The instance (value) that failed",
"type": ["null", "object"]
},
"name": {
"type": "string",
"description": "The keyword within the schema that failed."
},
"argument": {
"type": "array",
"description": "Provides information about the keyword that failed.",
"items": {
"type": "string"
}
},
"stack": {
"type": "string"
}
}
}
}
}
}
}
}
},
"required": ["path", "property", "message", "schema", "instance", "name", "argument", "stack"]
}Examples
401: Missing API Key
Missing API Key
{
"error": {
"message": "Missing API Key",
"status": "UNAUTHENTICATED"
}
}
401: Invalid API Key
Invalid API Key
{
"error": {
"message": "Invalid API Key",
"status": "UNAUTHENTICATED"
}
}
400: Invalid data
Invalid data
{
"error": {
"message": "Invalid data",
"status": "INVALID_ARGUMENT",
"details": {
"validation_errors": [
{
"path": [
"Details",
"Loan",
0,
"LoanType"
],
"property": "instance.Details.Loan[0].LoanType",
"message": "is not one of enum values: Existing,Proposed",
"schema": {
"type": "string",
"description": "Defines whether the applicant already has this loan or if it's a new loan",
"enum": [
"Existing",
"New"
]
},
"instance": "Proposed",
"name": "enum",
"argument": [
"Existing",
"Proposed"
],
"stack": "instance.Details.Loan[0].LoanType is not one of enum values: Existing,Proposed"
}
]
}
}
}
Invalid data: Invalid LoanId on Liability
Thrown when loan id specified on liability does not match a loan.
{
"error": {
"message": "Invalid data: Invalid LoanId specified on Liability",
"status": "INVALID_ARGUMENT",
"details": {
}
}
}
API Reference
Generate Report
The Generate Report endpoint accepts data about a customer's finances and lending scenario, along with lenders to calculate the report for. The endpoint may take a few seconds to generate a report which consists of a single loan amount case for each of the specified lenders.
Request
- Type:
POST - Path:
/engine/generate-report
Endpoint
The Generate Report endpoint can be accessed from the following URLs:
| Environment | Endpoint URL |
| Test | https://api.mre.test.blackfin.tools/engine/generate-report |
| Production | https://api.mre.blackfin.tools/engine/generate-report |
Authentication
An API_Key is required to call this endpoint. HTTP Bearer Token authentication is used.
JSON Schema
The request payload is sent as HTTP JSON body using the following schema:
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Request JSON Payload",
"type": "object",
"properties": {
"Details": {
"type": "object",
"description": "Main calculation details for mortgage calculation, see [CalculationDetails](https://docs.blackfin.tools/books/mortgagerecenginebackend/page/calculationdetails) schema"
},
"Lenders": {
"type": "array",
"description": "[Lender codes](https://docs.blackfin.tools/books/mortgagerecenginemycrm/page/lenders) to include in calculation. If no Lenders are passed (empty array), the calc will return ASB, ANZ, BNZ, AIA and Westpac by default",
"items": {
"type": "string",
"description": "",
"enum": [
"aia",
"anz",
"asb",
"bnz",
"co-op",
"kiwibank",
"liberty",
"sbs",
"tsb",
"westpac"
]
}
}
},
"required": [
"Details",
"Lenders"
]
}Examples
Example request payload:
JSON Request Body
{
"Details": {
"Loan": [
{
"LoanType": "New",
"Lender": null,
"LendingAction": null,
"LiabilityType": "HomeLoan",
"LoanAmount": 250000,
"TopUpAmount": null,
"TotalTermMonths": 180,
"InterestOnlyTermMonths": 180,
"Security": {
"Value": 300000,
"IsRBNZExempt": true,
"Location": null,
"PropertyType": [
"ResidentialProperty",
"FreeHoldResidential",
null
],
"SecurityType": "Proposed",
"UsageType": "OwnerOccupied"
},
"LoanId": 1
},
{
"LoanType": "Existing",
"Lender": null,
"LendingAction": "TopUp",
"LiabilityType": "HomeLoan",
"LoanAmount": 250000,
"TopUpAmount": 50000,
"TotalTermMonths": 183,
"InterestOnlyTermMonths": 219,
"Security": {
"Value": 300000,
"isRBNZExempt": false,
"Location": null,
"PropertyType": [
"ResidentialProperty",
"FreeHoldResidential",
null
],
"SecurityType": "Existing",
"UsageType": "OwnerOccupied"
},
"LoanId": 2
},
{
"LoanType": "Existing",
"Lender": null,
"LendingAction": "Refinance",
"LiabilityType": "HomeLoan",
"LoanAmount": 260000,
"TopUpAmount": null,
"TotalTermMonths": 180,
"InterestOnlyTermMonths": 216,
"Security": {
"Value": 300000,
"isRBNZExempt": false,
"Location": null,
"PropertyType": [
"ResidentialProperty",
"FreeHoldResidential",
null
],
"SecurityType": "Proposed",
"UsageType": "OwnerOccupied"
},
"LoanId": 3
},
{
"LoanType": "Existing",
"Lender": null,
"LendingAction": "Refinance",
"LiabilityType": "HomeLoan",
"LoanAmount": 370000,
"TopUpAmount": null,
"TotalTermMonths": 144,
"InterestOnlyTermMonths": 0,
"Security": {
"Value": 410000,
"isRBNZExempt": false,
"Location": null,
"PropertyType": [
null,
null,
null
],
"SecurityType": "Proposed",
"UsageType": null
},
"LoanId": 4
},
{
"LoanType": "Existing",
"Lender": null,
"LendingAction": "TopUp",
"LiabilityType": "HomeLoan",
"LoanAmount": 200000,
"TopUpAmount": 50000,
"TotalTermMonths": 180,
"InterestOnlyTermMonths": 0,
"Security": {
"Value": 210000,
"isRBNZExempt": false,
"Location": null,
"PropertyType": [
null,
null,
null
],
"SecurityType": "Proposed",
"UsageType": null
},
"LoanId": 5
}
],
"ApplicantParty": [
{
"Applicant": [
{
"ApplicantId": 1,
"Name": "Terence"
},
{
"ApplicantId": 2,
"Name": "Eve"
}
],
"Expense": [
{
"ApplicantId": 1,
"ExpenseType": "ChildCare",
"Frequency": "Monthly",
"Amount": 300
},
{
"ApplicantId": 1,
"ExpenseType": "ChildMaintenance",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "HigherEducationAndVocationalTraining",
"Frequency": "Monthly",
"Amount": 200
},
{
"ApplicantId": 1,
"ExpenseType": "OtherEducation",
"Frequency": "Monthly",
"Amount": 100
},
{
"ApplicantId": 1,
"ExpenseType": "PrivateSchoolCosts",
"Frequency": "Monthly",
"Amount": 300
},
{
"ApplicantId": 1,
"ExpenseType": "PublicSchoolCosts",
"Frequency": "Monthly",
"Amount": 150
},
{
"ApplicantId": 1,
"ExpenseType": "Groceries",
"Frequency": "Monthly",
"Amount": 200
},
{
"ApplicantId": 1,
"ExpenseType": "OtherGroceries",
"Frequency": "Monthly",
"Amount": 150
},
{
"ApplicantId": 1,
"ExpenseType": "BodyCorporatePrimaryResidence",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "CouncilRatesPrimaryResidence",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "ElectricityAndGasPrimaryResidence",
"Frequency": "Monthly",
"Amount": 100
},
{
"ApplicantId": 1,
"ExpenseType": "FurnishingsAndElectrical",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "HomeOperation",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "HomeRepairs",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "OtherPrimaryResidenceExpense",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "WaterAndSewerPrimaryResidence",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "BuildingInsurance",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "ContentsInsurance",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "HealthInsurance",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "IncomeProtection",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "LifeInsurance",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "OtherInsurance",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "VehicleInsurance",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "BodyCorporateInvestmentProperty",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "BuildingInsuranceInvestmentProperty",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "CouncilRatesInvestmentProperty",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "ElectricityAndGasInvestmentProperty",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "OtherInvestmentPropertyExpense",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "RepairsAndMaintenanceInvestmentProperty",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "RunningCostsInvestmentProperty",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "WaterAndSewerInvestmentProperty",
"Frequency": "Monthly",
"Amount": 200
},
{
"ApplicantId": 1,
"ExpenseType": "ContentsInsuranceSecondaryResidence",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "BodyCorporateSecondaryResidence",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "BuildingInsuranceSecondaryResidence",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "CouncilRatesSecondaryResidence",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "ElectricityAndGasSecondaryResidence",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "OtherSecondaryResidenceExpense",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "RepairsAndMaintenanceSecondaryResidence",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "RunningCostsSecondaryResidence",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "WaterAndSewerSecondaryResidence",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "MedicalAndHealth",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "NaturalTherapies",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "Board",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "DryCleaning",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "AlcoholTobacco",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "CinemaConcertsMemberships",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "GymSports",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "OtherRecreationalAndEntertainment",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "Pets",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "HomeMobilePhone",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "InternetPayTVAndMediaStreamingSubscriptions",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "PublicTransport",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "Registration",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "TaxiRideSharing",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "TollsParking",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "Kiwisaver",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "RegularDonations",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "VoluntarySaving",
"Frequency": "Monthly",
"Amount": 10
},
{
"ApplicantId": 1,
"ExpenseType": "VoluntarySuper",
"Frequency": "Monthly",
"Amount": 10
}
],
"Income": [
{
"ApplicantId": 1,
"Frequency": "Yearly",
"Amount": 50000,
"AmountType": "Gross",
"IncomeType": "SalaryWages",
"Attributes": []
},
{
"ApplicantId": 1,
"Frequency": "Yearly",
"Amount": 5000,
"AmountType": "Gross",
"IncomeType": "RentalIncome",
"Attributes": [
{
"name": "PropertyBuildDate",
"value": "2018-11-06"
},
{
"name": "PropertyCountry",
"value": "NZ"
},
{
"name": "IsTaxExempt",
"value": true
},
{
"name": "SalePurchaseDate",
"value": "2019-11-11"
}
]
},
{
"ApplicantId": 2,
"Frequency": "Yearly",
"Amount": 40000,
"AmountType": "Gross",
"IncomeType": "SalaryWages",
"Attributes": []
},
{
"ApplicantId": 2,
"Frequency": "Yearly",
"Amount": 5000,
"AmountType": "Gross",
"IncomeType": "WorkAllowance",
"Attributes": []
},
{
"ApplicantId": 1,
"Frequency": "Yearly",
"Amount": 10000,
"AmountType": "Gross",
"IncomeType": "Bonus",
"Attributes": []
},
{
"ApplicantId": 1,
"Frequency": "Yearly",
"Amount": 4000,
"AmountType": "Gross",
"IncomeType": "BoarderIncome",
"Attributes": [
{
"name": "BoarderIncomeType",
"value": "AllInclusive"
}
]
},
{
"ApplicantId": 1,
"Frequency": "Yearly",
"Amount": 3000,
"AmountType": "Gross",
"IncomeType": "CarAllowance",
"Attributes": []
},
{
"ApplicantId": 1,
"Frequency": "Yearly",
"Amount": 5000,
"AmountType": "Gross",
"IncomeType": "FamilyAllowance",
"Attributes": []
}
],
"Liability": [
{
"ApplicantId": 1,
"LiabilityType": "HomeLoan",
"RepaymentAmount": 2000,
"RepaymentFrequency": "Monthly",
"Limit": 4000,
"Balance": 10000,
"InterestRate": 0.02,
"RepaymentType": "PrincipalInterest",
"StartDate": "2017-11-15",
"TotalTermMonths": 228,
"InterestOnlyTermMonths": 228,
"Lender": "Kiwibank",
"IsRevolvingCredit": true
},
{
"ApplicantId": 1,
"LiabilityType": "CreditCard",
"RepaymentAmount": null,
"RepaymentFrequency": null,
"Limit": 30000,
"Balance": null,
"InterestRate": null,
"RepaymentType": null,
"StartDate": null,
"TotalTermMonths": null,
"InterestOnlyTermMonths": null,
"Lender": null,
"IsRevolvingCredit": null
},
{
"ApplicantId": 1,
"LiabilityType": "PersonalLoan",
"RepaymentAmount": 2000,
"RepaymentFrequency": "Monthly",
"Limit": 4000,
"Balance": 30000,
"InterestRate": 0.02,
"RepaymentType": null,
"StartDate": "2019-11-07",
"TotalTermMonths": 220,
"InterestOnlyTermMonths": null,
"Lender": null,
"IsRevolvingCredit": true
},
{
"ApplicantId": 1,
"LiabilityType": "Other",
"RepaymentAmount": 200,
"RepaymentFrequency": "Monthly",
"Limit": 4000,
"Balance": 10000,
"InterestRate": 0.01,
"RepaymentType": null,
"StartDate": "2018-11-07",
"TotalTermMonths": 183,
"InterestOnlyTermMonths": null,
"Lender": "Kiwibank",
"IsRevolvingCredit": true
},
{
"ApplicantId": 1,
"LiabilityType": "HirePurchase",
"RepaymentAmount": 2000,
"RepaymentFrequency": "Monthly",
"Limit": null,
"Balance": 20000,
"InterestRate": null,
"RepaymentType": null,
"StartDate": null,
"TotalTermMonths": null,
"InterestOnlyTermMonths": null,
"Lender": null,
"IsRevolvingCredit": null
},
{
"ApplicantId": 1,
"LiabilityType": "Overdraft",
"RepaymentAmount": 2000,
"RepaymentFrequency": "Monthly",
"Limit": 4000,
"Balance": 20000,
"InterestRate": 0.02,
"RepaymentType": null,
"StartDate": null,
"TotalTermMonths": null,
"InterestOnlyTermMonths": null,
"Lender": null,
"IsRevolvingCredit": null
},
{
"LoanId": 2,
"Lender": null,
"Balance": 195000,
"Limit": 250000,
"InterestRate": 1,
"RepaymentAmount": 15000,
"RepaymentFrequency": "Monthly",
"RepaymentType": null,
"TotalTermMonths": 183,
"StartDate": null,
"IsRevolvingCredit": null,
"InterestOnlyTermMonths": 216,
"ApplicantId": 1,
"LiabilityType": "HomeLoan"
},
{
"Lender": null,
"Balance": 200000,
"Limit": 260000,
"InterestRate": 2,
"RepaymentAmount": 10000,
"RepaymentFrequency": "Monthly",
"RepaymentType": "PrincipalInterest",
"TotalTermMonths": 180,
"StartDate": null,
"IsRevolvingCredit": null,
"InterestOnlyTermMonths": 216,
"ApplicantId": 1,
"LiabilityType": "HomeLoan",
"LoanId": 3
}
],
"NumberOfDependents": 1,
"NumberOfVehicles": 1
}
]
},
"Lenders": []
}
Validation
The API performs basic validation on the structure of the request payload but does not impose strict rules based on what is required for generating a calculation. Same rules are applied as for create session endpoint, this will be fixed eventually to throw an error when there is insufficient data.
Response
Success
If the Generate Report completes successfully:
JSON Body
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Result Response Schema",
"type": "object",
"properties": {
"Result": {
"type": "object",
"description": "Contains the calculation results",
"properties": {
"Report": {
"type": "object",
"description": "Report details and results. See [this schema](https://docs.blackfin.tools/books/mortgagerecenginebackend/page/report) for more information."
}
},
"required": ["Report"]
},
"ReportId": {
"type": "string",
"description": "Unique identifier for the report"
}
},
"required": ["Result", "ReportId"]
}
Examples
200: Success
Success Response
{
"Result": {
"Report": {
"Id": "7Z0nc3ZJ",
"Cases": [
{
"Id": 1,
"LoanAmount": 350000,
"LenderResult": [
{
"Lender": {
"Id": 1,
"Key": "aia",
"Name": "AIA",
"Logo": "https://storage.googleapis.com/mortgage-rec-engine-dev.appspot.com/lender-logos/aia.png"
},
"Result": {
"AssessedIncome": [
{
"Group": "Applicant Income",
"Label": "Total Income (Gary) - including Salary",
"Entered": {
"Amount": null,
"Frequency": null
},
"Assessed": {
"Amount": 5472,
"Frequency": "Monthly"
}
},
{
"Group": "Applicant Income",
"Label": "Total Income (Lynne) - including Salary",
"Entered": {
"Amount": null,
"Frequency": null
},
"Assessed": {
"Amount": 3368,
"Frequency": "Monthly"
}
}
],
"AssessedExpense": [
{
"Group": "Lending",
"Label": "New Home Loan",
"Entered": {
"Amount": 350000,
"InterestRate": 0.067
},
"Assessed": {
"Amount": 2258.47,
"Frequency": "Monthly"
}
},
{
"Group": "Lending",
"Label": "Credit Card",
"Entered": {
"Amount": 10000,
"Definition": "Limit"
},
"Assessed": {
"Amount": 0,
"Frequency": "Monthly"
}
},
{
"Group": "Living Expenses",
"Label": "Food",
"Entered": {
"Amount": 700,
"Frequency": "Monthly"
},
"Assessed": {
"Amount": 0,
"Frequency": "Monthly"
}
},
{
"Group": "Living Expenses",
"Label": "Utilities",
"Entered": {
"Amount": 400,
"Frequency": "Monthly"
},
"Assessed": {
"Amount": 0,
"Frequency": "Monthly"
}
},
{
"Group": "Living Expenses",
"Label": "Ongoing Household Expenses",
"Entered": {
"Amount": 100,
"Frequency": "Monthly"
},
"Assessed": {
"Amount": 0,
"Frequency": "Monthly"
}
},
{
"Group": "Living Expenses",
"Label": "ChildCare",
"Entered": {
"Amount": 250,
"Frequency": "Monthly"
},
"Assessed": {
"Amount": 0,
"Frequency": "Monthly"
}
},
{
"Group": "Living Expenses",
"Label": "Health/Medical/Funeral/Pet Insurance",
"Entered": {
"Amount": 480,
"Frequency": "Monthly"
},
"Assessed": {
"Amount": 0,
"Frequency": "Monthly"
}
},
{
"Group": " Living Expenses",
"Label": "Minimum Living Expenses",
"Entered": {
"Amount": 1930,
"Frequency": "Monthly"
},
"Assessed": {
"Amount": 2876,
"Frequency": "Monthly"
}
}
],
"TotalMonthlyIncome": 8840,
"TotalMonthlyExpense": 2558.47,
"UMI": {
"Value": 3405.53,
"Required": 120,
"Status": "Pass",
"SecurityUsageType": "OwnerOccupied",
"LvrValue": 0.7
},
"Servicing": {
"Type": "N/A",
"Value": 0,
"Required": 0,
"Status": "Fail"
},
"LVR": [
{
"Reference": "Result.LVR.LVRLimit[0]",
"LoanId": 1,
"LVRLimit": [
{
"Label": "Property Type",
"Description": "Unknown",
"MaxLVR": 0.9
},
{
"Label": "Usage Type",
"Description": "Unknown",
"MaxLVR": 0.9
}
],
"Value": 0.7,
"RequiredMaxLVR": 0.9,
"Status": "Pass"
}
],
"LEM": [],
"DTI": {
"TotalIncome": 133000,
"TotalDebt": 360000,
"Value": 2.71,
"RequiredMaxDTI": 7,
"Status": "Pass"
},
"Deposit": {
"Amount": 0
},
"MaxLoanAmount": 859100
},
"Warnings": [
{
"Message": "Entered Living Expenses of $1930 is below minimum expected ($2876)",
"Reference": "Result.Expenses"
}
],
"Errors": [],
"Resources": [
{
"Type": "Image",
"Reference": "Result.LVR.LVRLimit[1]",
"URL": "https://storage.googleapis.com/mortgage-rec-engine-dev.appspot.com/lender-guidelines/aia_UsageType.png"
}
],
"Accuracy": 0.69,
"Version": {
"VersionNumber": "v2.80",
"ReleaseDate": "2025-11-26",
"VersionReleaseNote": ""
},
"SpreadsheetFileURL": "https://api.mre.test.blackfin.tools/engine/download-spreadsheet?report_id=7Z0nc3ZJ&case_id=1&lender=aia"
},
{
"Lender": {
"Id": 2,
"Key": "anz",
"Name": "ANZ",
"Logo": "https://storage.googleapis.com/mortgage-rec-engine-dev.appspot.com/lender-logos/anz.png"
},
"Result": {
"AssessedIncome": [
{
"Group": "Customer Income",
"Label": "Customer Income (Gary)",
"Entered": {
"Amount": 85000,
"Frequency": "Yearly"
},
"Assessed": {
"Amount": 5471.08,
"Frequency": "Monthly"
}
},
{
"Group": "Customer Income",
"Label": "Customer Income (Lynne)",
"Entered": {
"Amount": 4000,
"Frequency": "Monthly"
},
"Assessed": {
"Amount": 3324.2,
"Frequency": "Monthly"
}
}
],
"AssessedExpense": [
{
"Group": "Lending",
"Label": "New Home Loan",
"Entered": {
"Amount": 350000,
"InterestRate": 0.067
},
"Assessed": {
"Amount": 2258.47,
"Frequency": "Monthly"
}
},
{
"Group": "Other Liabilities",
"Label": "Credit Cards",
"Entered": {
"Amount": 10000,
"Definition": "Limit"
},
"Assessed": {
"Amount": 400,
"Frequency": "Monthly"
}
},
{
"Group": "Living Expenses",
"Label": "All Living Expenses",
"Entered": {
"Amount": 1100,
"Frequency": "Monthly"
},
"Assessed": {
"Amount": 2198,
"Frequency": "Monthly"
}
},
{
"Group": "Living Expenses",
"Label": "Other Significant Expenses",
"Entered": {
"Amount": 730,
"Frequency": "Monthly"
},
"Assessed": {
"Amount": 730,
"Frequency": "Monthly"
}
}
],
"TotalMonthlyIncome": 8795.28,
"TotalMonthlyExpense": 5586.47,
"UMI": {
"Value": 3208.81,
"Required": 100,
"Status": "Pass"
},
"Servicing": {
"Type": "N/A",
"Value": 0,
"Required": 0,
"Status": "Fail"
},
"LVR": [
{
"Reference": "Result.LVR.LVRLimit[0]",
"SecurityId": 1,
"LVRLimit": [
{
"Label": "Property Type",
"Description": "Unknown",
"MaxLVR": 0.9
},
{
"Label": "Usage Type",
"Description": "Unknown",
"MaxLVR": 0.9
}
],
"Value": 0.7,
"RequiredMaxLVR": 0.9,
"Status": "Pass"
}
],
"LEM": [],
"DTI": {
"TotalIncome": 0,
"TotalDebt": 0,
"Value": 0,
"RequiredMaxDTI": "N/A",
"Status": "N/A"
},
"Deposit": {
"Amount": 0
},
"MaxLoanAmount": 831700
},
"Warnings": [],
"Errors": [],
"Resources": [
{
"Type": "Image",
"Reference": "Result.LVR.LVRLimit[0]",
"URL": "https://storage.googleapis.com/mortgage-rec-engine-dev.appspot.com/lender-guidelines/anz_PropertyType.jpg"
},
{
"Type": "Image",
"Reference": "Result.LVR.LVRLimit[1]",
"URL": "https://storage.googleapis.com/mortgage-rec-engine-dev.appspot.com/lender-guidelines/anz_UsageType.jpg"
}
],
"Accuracy": 0.69,
"Version": {
"VersionNumber": "v10.9",
"ReleaseDate": "2025-10-23",
"VersionReleaseNote": ""
},
"SpreadsheetFileURL": "https://api.mre.test.blackfin.tools/engine/download-spreadsheet?report_id=7Z0nc3ZJ&case_id=1&lender=anz"
},
{
"Lender": {
"Id": 3,
"Key": "asb",
"Name": "ASB",
"Logo": "https://storage.googleapis.com/mortgage-rec-engine-dev.appspot.com/lender-logos/asb.png"
},
"Result": {
"AssessedIncome": [
{
"Group": "Applicant Income",
"Label": "Total Income (Gary) - including Salary",
"Entered": {
"Amount": null,
"Frequency": null
},
"Assessed": {
"Amount": 5472,
"Frequency": "Monthly"
}
},
{
"Group": "Applicant Income",
"Label": "Total Income (Lynne) - including Salary",
"Entered": {
"Amount": null,
"Frequency": null
},
"Assessed": {
"Amount": 3368,
"Frequency": "Monthly"
}
}
],
"AssessedExpense": [
{
"Group": "Lending",
"Label": "New Home Loan",
"Entered": {
"Amount": 350000,
"InterestRate": 0.067
},
"Assessed": {
"Amount": 2258.47,
"Frequency": "Monthly"
}
},
{
"Group": "Lending",
"Label": "Credit Card",
"Entered": {
"Amount": 10000,
"Definition": "Limit"
},
"Assessed": {
"Amount": 0,
"Frequency": "Monthly"
}
},
{
"Group": "Living Expenses",
"Label": "Food",
"Entered": {
"Amount": 700,
"Frequency": "Monthly"
},
"Assessed": {
"Amount": 0,
"Frequency": "Monthly"
}
},
{
"Group": "Living Expenses",
"Label": "Utilities",
"Entered": {
"Amount": 400,
"Frequency": "Monthly"
},
"Assessed": {
"Amount": 0,
"Frequency": "Monthly"
}
},
{
"Group": "Living Expenses",
"Label": "Ongoing Household Expenses",
"Entered": {
"Amount": 100,
"Frequency": "Monthly"
},
"Assessed": {
"Amount": 0,
"Frequency": "Monthly"
}
},
{
"Group": "Living Expenses",
"Label": "ChildCare",
"Entered": {
"Amount": 250,
"Frequency": "Monthly"
},
"Assessed": {
"Amount": 0,
"Frequency": "Monthly"
}
},
{
"Group": "Living Expenses",
"Label": "Health/Medical/Funeral/Pet Insurance",
"Entered": {
"Amount": 480,
"Frequency": "Monthly"
},
"Assessed": {
"Amount": 0,
"Frequency": "Monthly"
}
},
{
"Group": " Living Expenses",
"Label": "Minimum Living Expenses",
"Entered": {
"Amount": 1930,
"Frequency": "Monthly"
},
"Assessed": {
"Amount": 2876,
"Frequency": "Monthly"
}
}
],
"TotalMonthlyIncome": 8840,
"TotalMonthlyExpense": 2558.47,
"UMI": {
"Value": 3405.53,
"Required": 120,
"Status": "Pass",
"SecurityUsageType": "OwnerOccupied",
"LvrValue": 0.7
},
"Servicing": {
"Type": "N/A",
"Value": 0,
"Required": 0,
"Status": "Fail"
},
"LVR": [
{
"Reference": "Result.LVR.LVRLimit[0]",
"LoanId": 1,
"LVRLimit": [
{
"Label": "Property Type",
"Description": "Unknown",
"MaxLVR": 0.9
},
{
"Label": "Usage Type",
"Description": "Unknown",
"MaxLVR": 0.9
}
],
"Value": 0.7,
"RequiredMaxLVR": 0.9,
"Status": "Pass"
}
],
"LEM": [],
"DTI": {
"TotalIncome": 133000,
"TotalDebt": 360000,
"Value": 2.71,
"RequiredMaxDTI": 7,
"Status": "Pass"
},
"Deposit": {
"Amount": 0
},
"MaxLoanAmount": 859100
},
"Warnings": [
{
"Message": "Entered Living Expenses of $1930 is below minimum expected ($2876)",
"Reference": "Result.Expenses"
}
],
"Errors": [],
"Resources": [
{
"Type": "Image",
"Reference": "Result.LVR.LVRLimit[1]",
"URL": "https://storage.googleapis.com/mortgage-rec-engine-dev.appspot.com/lender-guidelines/asb_UsageType.png"
},
{
"Type": "Image",
"Reference": "Result.DTI",
"URL": "https://storage.googleapis.com/mortgage-rec-engine-dev.appspot.com/lender-guidelines/asb_DTI.png"
}
],
"Accuracy": 0.69,
"Version": {
"VersionNumber": "v2.80",
"ReleaseDate": "2025-11-26",
"VersionReleaseNote": ""
},
"SpreadsheetFileURL": "https://api.mre.test.blackfin.tools/engine/download-spreadsheet?report_id=7Z0nc3ZJ&case_id=1&lender=asb"
},
{
"Lender": {
"Id": 4,
"Key": "bnz",
"Name": "BNZ",
"Logo": "https://storage.googleapis.com/mortgage-rec-engine-dev.appspot.com/lender-logos/bnz.png"
},
"Result": {
"AssessedIncome": [
{
"Group": "Customer Income",
"Label": "Customer Income (Gary)",
"Entered": {
"Amount": 85000,
"Frequency": "Yearly"
},
"Assessed": {
"Amount": 65653,
"Frequency": "Monthly"
}
},
{
"Group": "Customer Income",
"Label": "Customer Income (Lynne)",
"Entered": {
"Amount": 48000,
"Frequency": "Yearly"
},
"Assessed": {
"Amount": 39890.4,
"Frequency": "Monthly"
}
}
],
"AssessedExpense": [
{
"Group": "Lending",
"Label": "New Home Loan",
"Entered": {
"Amount": 350000,
"InterestRate": 0.0685
},
"Assessed": {
"Amount": 2293.41,
"Frequency": "Monthly"
}
},
{
"Group": "Other Financial Commitments",
"Label": "Credit Cards",
"Entered": {
"Amount": 10000,
"Definition": "Limit"
},
"Assessed": {
"Amount": 380,
"Frequency": "Monthly"
}
},
{
"Group": "Declared Living Expenses",
"Label": "Childcare & Education",
"Entered": {
"Amount": 250,
"Frequency": "m"
},
"Assessed": {
"Amount": 250,
"Frequency": "Monthly"
}
},
{
"Group": "Declared Living Expenses",
"Label": "Utilities",
"Entered": {
"Amount": 400,
"Frequency": "m"
},
"Assessed": {
"Amount": 400,
"Frequency": "Monthly"
}
},
{
"Group": "Declared Living Expenses",
"Label": "Food & Groceries",
"Entered": {
"Amount": 700,
"Frequency": "m"
},
"Assessed": {
"Amount": 700,
"Frequency": "Monthly"
}
},
{
"Group": "Declared Living Expenses",
"Label": "Insurances",
"Entered": {
"Amount": 480,
"Frequency": "m"
},
"Assessed": {
"Amount": 480,
"Frequency": "Monthly"
}
},
{
"Group": "Declared Living Expenses",
"Label": "Other regular expenses",
"Entered": {
"Amount": 100,
"Frequency": "m"
},
"Assessed": {
"Amount": 100,
"Frequency": "Monthly"
}
}
],
"TotalMonthlyIncome": 8795.28,
"TotalMonthlyExpense": 5839.41,
"UMI": {
"Value": 2955.88,
"Required": "N/A",
"Status": "Pass"
},
"Servicing": {
"Type": "N/A",
"Value": 0,
"Required": 0,
"Status": "Fail"
},
"LVR": [
{
"Reference": "Result.LVR.LVRLimit[0]",
"LoanId": 1,
"LVRLimit": [
{
"Label": "Property Type",
"Description": "Unknown",
"MaxLVR": 0.8
}
],
"Value": 0.7,
"RequiredMaxLVR": 0.8,
"Status": "Pass"
}
],
"LEM": [],
"DTI": {
"TotalIncome": 133000,
"TotalDebt": 360000,
"Value": 2.71,
"RequiredMaxDTI": "N/A",
"Status": "N/A"
},
"Deposit": {
"Amount": 0
},
"MaxLoanAmount": 762900
},
"Warnings": [
{
"Message": "Declared Living Expenses of $1930 is below minimum expected ($3166)",
"Reference": "Result.Expenses"
}
],
"Errors": [],
"Resources": [
{
"Type": "Image",
"Reference": "Result.LVR.LVRLimit[0]",
"URL": "https://storage.googleapis.com/mortgage-rec-engine-dev.appspot.com/lender-guidelines/bnz_PropertyType.png"
}
],
"Accuracy": 0.69,
"Version": {
"VersionNumber": "v12.29",
"ReleaseDate": "2025-10-23",
"VersionReleaseNote": ""
},
"SpreadsheetFileURL": "https://api.mre.test.blackfin.tools/engine/download-spreadsheet?report_id=7Z0nc3ZJ&case_id=1&lender=bnz"
},
{
"Lender": {
"Id": 5,
"Key": "co-op",
"Name": "CO-OP",
"Logo": "https://storage.googleapis.com/mortgage-rec-engine-dev.appspot.com/lender-logos/coop.png"
},
"Result": {
"AssessedIncome": [
{
"Group": "Gross Income",
"Label": "Applicant 1",
"Entered": {
"Amount": 85000,
"Frequency": "Annual"
},
"Assessed": {
"Amount": 5476.04,
"Frequency": "Monthly"
}
},
{
"Group": "Gross Income",
"Label": "Applicant 2",
"Entered": {
"Amount": 4000,
"Frequency": "Monthly"
},
"Assessed": {
"Amount": 3327,
"Frequency": "Monthly"
}
}
],
"AssessedExpense": [
{
"Group": "Lending",
"Label": "New Home Loan",
"Entered": {
"Amount": 350000,
"InterestRate": 0.065
},
"Assessed": {
"Amount": 2212.24,
"Frequency": "Monthly"
}
},
{
"Group": "Fixed Commitments",
"Label": "Life & Medical Insurance ",
"Entered": {
"Amount": 480,
"Frequency": "Monthly"
},
"Assessed": {
"Amount": 480,
"Frequency": "Monthly"
}
},
{
"Group": "Fixed Commitments",
"Label": "Child Care",
"Entered": {
"Amount": 250,
"Frequency": "Monthly"
},
"Assessed": {
"Amount": 250,
"Frequency": "Monthly"
}
},
{
"Group": "Fixed Commitments",
"Label": "Insurance Default",
"Entered": {
"Amount": 0,
"Frequency": "Monthly"
},
"Assessed": {
"Amount": 152.19,
"Frequency": "Monthly"
}
},
{
"Group": "Living Expenses",
"Label": "Benchmark Expenses",
"Entered": {
"Amount": 1200,
"Frequency": "Monthly"
},
"Assessed": {
"Amount": 2728.5,
"Frequency": "Monthly"
}
}
],
"TotalMonthlyIncome": 8803.04,
"TotalMonthlyExpense": 6202.93,
"UMI": {
"Value": 1195.94,
"Required": 108.33,
"Status": "Pass"
},
"Servicing": {
"Type": "N/A",
"Value": 0,
"Required": 0,
"Status": "Fail"
},
"LVR": [
{
"Reference": "Result.LVR.LVRLimit[0]",
"LoanId": null,
"SecurityId": 1,
"LVRLimit": [
{
"Label": "Property Type",
"Description": "Unknown",
"MaxLVR": 0.9
}
],
"Value": 0.7,
"RequiredMaxLVR": 0.9,
"Status": "Pass"
}
],
"LEM": [
{
"Label": "Total Lending",
"LoanId": null,
"Assessed": 0.7,
"Margin": null,
"Amount": null
}
],
"DTI": {
"TotalIncome": 133000,
"TotalDebt": 360000,
"Value": 2.71,
"RequiredMaxDTI": "N/A",
"Status": "N/A"
},
"Deposit": {
"Amount": 0
},
"MaxLoanAmount": 744200
},
"Warnings": [
{
"Message": "Entered Living Expenses are below minimum expected (2728.5). Benchmark values have been used.",
"Reference": "Result.Expenses"
}
],
"Errors": [],
"Resources": [
{
"Type": "Image",
"Reference": "Result.LVR.LVRLimit[0]",
"URL": "https://storage.googleapis.com/mortgage-rec-engine-dev.appspot.com/lender-guidelines/co-op_PropertyType.png"
}
],
"Accuracy": 0.69,
"Version": {
"VersionNumber": "v6.9",
"ReleaseDate": "2025-08-26",
"VersionReleaseNote": ""
},
"SpreadsheetFileURL": "https://api.mre.test.blackfin.tools/engine/download-spreadsheet?report_id=7Z0nc3ZJ&case_id=1&lender=co-op"
},
{
"Lender": {
"Id": 6,
"Key": "kiwibank",
"Name": "Kiwibank",
"Logo": "https://storage.googleapis.com/mortgage-rec-engine-dev.appspot.com/lender-logos/kiwibank.png"
},
"Result": {
"AssessedIncome": [
{
"Group": "Customer Income",
"Label": "Total Income (Gary) - including Salary ",
"Entered": {
"Amount": null,
"Frequency": null
},
"Assessed": {
"Amount": 5471.08,
"Frequency": "Monthly"
}
},
{
"Group": "Customer Income",
"Label": "Total Income (Lynne) - including Salary ",
"Entered": {
"Amount": null,
"Frequency": null
},
"Assessed": {
"Amount": 3324.2,
"Frequency": "Monthly"
}
}
],
"AssessedExpense": [
{
"Group": "Proposed Lending",
"Label": "New Home Loan",
"Entered": {
"Amount": 350000,
"InterestRate": 0.068
},
"Assessed": {
"Amount": 2281.74,
"Frequency": "Monthly"
}
},
{
"Group": "Existing Debt Commitments",
"Label": "Card 1",
"Entered": {
"Amount": 10000,
"Definition": "Limit"
},
"Assessed": {
"Amount": 500,
"Frequency": "Monthly"
}
},
{
"Group": "Benchmarkable Expenses",
"Label": "Groceries and Food",
"Entered": {
"Amount": 700,
"Frequency": "Monthly"
},
"Assessed": {
"Amount": 0,
"Frequency": "Monthly"
}
},
{
"Group": "Benchmarkable Expenses",
"Label": "Electricity, Gas and Heating",
"Entered": {
"Amount": 400,
"Frequency": "Monthly"
},
"Assessed": {
"Amount": 0,
"Frequency": "Monthly"
}
},
{
"Group": "Benchmarkable Expenses",
"Label": "Housing Repairs and Maintenance",
"Entered": {
"Amount": 100,
"Frequency": "Monthly"
},
"Assessed": {
"Amount": 0,
"Frequency": "Monthly"
}
},
{
"Group": "Benchmarkable Expenses",
"Label": "Minimum Household Expenditure Benchmark (HEB)",
"Entered": {
"Amount": 1200,
"Frequency": "Monthly"
},
"Assessed": {
"Amount": 2384.47,
"Frequency": "Monthly"
}
},
{
"Group": "Non Benchmarkable Expenses",
"Label": "Insurance - Life, Health & Income",
"Entered": {
"Amount": 480,
"Frequency": "Monthly"
},
"Assessed": {
"Amount": 480,
"Frequency": "Monthly"
}
},
{
"Group": "Non Benchmarkable Expenses",
"Label": "Child Care",
"Entered": {
"Amount": 250,
"Frequency": "Monthly"
},
"Assessed": {
"Amount": 250,
"Frequency": "Monthly"
}
}
],
"TotalMonthlyIncome": 8795.28,
"TotalMonthlyExpense": 5896.21,
"UMI": {
"Value": 0,
"Required": 0,
"Status": "Fail"
},
"Servicing": {
"Type": "NSR",
"Value": 0.67,
"Required": 1,
"Status": "Pass"
},
"LVR": [
{
"Reference": "Result.LVR.LVRLimit[0]",
"LoanId": null,
"SecurityId": 1,
"LVRLimit": [
{
"Label": "Property Type",
"Description": "Unknown ",
"MaxLVR": 0.9
}
],
"Value": 0.7,
"RequiredMaxLVR": 0.9,
"Status": "Pass"
}
],
"LEM": [
{
"Label": "Total Lending",
"LoanId": null,
"Assessed": 0.7,
"Margin": 0,
"Amount": null
}
],
"DTI": {
"TotalIncome": 133000,
"TotalDebt": 360000,
"Value": 2.71,
"RequiredMaxDTI": 6,
"Status": "Pass"
},
"Deposit": {
"Amount": 0
},
"MaxLoanAmount": 794600
},
"Warnings": [
{
"Message": "Entered Benchmarkable Expenses of $1200 is below minimum expected ($2384.47)",
"Reference": "Result.Expenses"
}
],
"Errors": [],
"Resources": [
{
"Type": "Image",
"Reference": "Result.LVR.LVRLimit[0]",
"URL": "https://storage.googleapis.com/mortgage-rec-engine-dev.appspot.com/lender-guidelines/kiwibank_PropertyType.png"
}
],
"Accuracy": 0.69,
"Version": {
"VersionNumber": "v67.1",
"ReleaseDate": "2025-11-24",
"VersionReleaseNote": ""
},
"SpreadsheetFileURL": "https://api.mre.test.blackfin.tools/engine/download-spreadsheet?report_id=7Z0nc3ZJ&case_id=1&lender=kiwibank"
},
{
"Lender": {
"Id": 7,
"Key": "liberty",
"Name": "Liberty",
"Logo": "https://storage.googleapis.com/mortgage-rec-engine-dev.appspot.com/lender-logos/liberty.png"
},
"Result": {
"AssessedIncome": [
{
"Group": "Gross Income",
"Label": "Gross Income (Gary)",
"Entered": {
"Amount": 85000,
"Frequency": "Yearly"
},
"Assessed": {
"Amount": 5476.04,
"Frequency": "Monthly"
}
},
{
"Group": "Gross Income",
"Label": "Gross Income (Lynne)",
"Entered": {
"Amount": 48000,
"Frequency": "Yearly"
},
"Assessed": {
"Amount": 3327,
"Frequency": "Monthly"
}
}
],
"AssessedExpense": [
{
"Group": "Living Expenses",
"Label": "Declared living expenses",
"Entered": {
"Amount": 1930,
"Frequency": "Monthly"
},
"Assessed": {
"Amount": 3309,
"Frequency": "Monthly"
}
},
{
"Group": "Lending",
"Label": "New Home Loan",
"Entered": {
"Amount": 350000,
"InterestRate": 0.1
},
"Assessed": {
"Amount": 2966,
"Frequency": "Monthly"
}
},
{
"Group": "Other Liabilities",
"Label": "Credit Card",
"Entered": {
"Amount": 10000,
"Definition": "Limit"
},
"Assessed": {
"Amount": 380,
"Frequency": "Monthly"
}
}
],
"TotalMonthlyIncome": 8803.04,
"TotalMonthlyExpense": 6655,
"UMI": {
"Value": 2148.04,
"Required": 0,
"Status": "Pass"
},
"Servicing": {
"Type": "N/A",
"Value": 0,
"Required": 0,
"Status": "Fail"
},
"LVR": [
{
"Reference": "Result.LVR.LVRLimit[0]",
"LoanId": null,
"SecurityId": 1,
"LVRLimit": [
{
"Label": "Usage Type",
"Description": "Unknown",
"MaxLVR": 0.9
}
],
"Value": 0.7,
"RequiredMaxLVR": 0.9,
"Status": "Pass"
}
],
"LEM": [],
"DTI": {
"TotalIncome": 0,
"TotalDebt": 0,
"Value": 0,
"RequiredMaxDTI": "N/A",
"Status": "N/A"
},
"Deposit": {
"Amount": 0
},
"MaxLoanAmount": 603400
},
"Warnings": [
{
"Message": "Declared Living Expenses are below minimum expected ($3309). Benchmark values have been used.",
"Reference": "Result.Expenses"
},
{
"Message": "This Max LVR includes a 10% Boost Loan. Property types are assessed on a case-by-case basis.",
"ReferenceObjectType": "Security",
"ReferenceObjectId": 1,
"Reference": "Result.LVR"
}
],
"Errors": [],
"Resources": [
{
"Type": "Image",
"Reference": "Result.LVR.LVRLimit[0]",
"URL": "https://storage.googleapis.com/mortgage-rec-engine-dev.appspot.com/lender-guidelines/liberty_LVR.png"
}
],
"Accuracy": 0.69,
"Version": {
"VersionNumber": "",
"ReleaseDate": "",
"VersionReleaseNote": ""
},
"SpreadsheetFileURL": "https://api.mre.test.blackfin.tools/engine/download-spreadsheet?report_id=7Z0nc3ZJ&case_id=1&lender=liberty"
},
{
"Lender": {
"Id": 8,
"Key": "sbs",
"Name": "SBS",
"Logo": "https://storage.googleapis.com/mortgage-rec-engine-dev.appspot.com/lender-logos/sbs.png"
},
"Result": {
"AssessedIncome": [
{
"Group": "Applicant Income",
"Label": "Gary",
"Entered": {
"Amount": 85000,
"Frequency": "Yearly"
},
"Assessed": {
"Amount": 5471.08,
"Frequency": "Monthly"
}
},
{
"Group": "Applicant Income",
"Label": "Lynne",
"Entered": {
"Amount": 48000,
"Frequency": "Yearly"
},
"Assessed": {
"Amount": 3324.2,
"Frequency": "Monthly"
}
}
],
"AssessedExpense": [
{
"Group": "Lending",
"Label": "New Home Loan",
"Entered": {
"Amount": 350000,
"InterestRate": 0.065
},
"Assessed": {
"Amount": 2212.24,
"Frequency": "Monthly"
}
},
{
"Group": "Lending",
"Label": "Total Credit/Store Card Limits",
"Entered": {
"Amount": 10000,
"Definition": "Limit"
},
"Assessed": {
"Amount": 380,
"Frequency": "Monthly"
}
},
{
"Group": "Living Expenses",
"Label": "Living & Other Expenses",
"Entered": {
"Amount": 1930,
"Frequency": "Monthly"
},
"Assessed": {
"Amount": 3525,
"Frequency": "Monthly"
}
}
],
"TotalMonthlyIncome": 8795.28,
"TotalMonthlyExpense": 6117.24,
"UMI": {
"Value": 0,
"Required": 0,
"Status": "Fail"
},
"Servicing": {
"Type": "NSR",
"Value": 0.7,
"Required": 0.95,
"Status": "Pass"
},
"LVR": [
{
"Reference": "Result.LVR.LVRLimit[0]",
"SecurityId": 1,
"LVRLimit": [
{
"Label": "Property Type",
"Description": "Unknown ",
"MaxLVR": 0.8
}
],
"Value": 0.7,
"RequiredMaxLVR": 0.8,
"Status": "Pass"
}
],
"LEM": [],
"DTI": {
"TotalIncome": 133000,
"TotalDebt": 360000,
"Value": 2.71,
"RequiredMaxDTI": 6,
"Status": "Pass"
},
"Deposit": {
"Amount": 0
},
"MaxLoanAmount": 738900
},
"Warnings": [
{
"Message": "Entered Living Expenses are below minimum expected ($3525). Benchmark values have been used.",
"Reference": "Result.Expenses"
}
],
"Errors": [],
"Resources": [
{
"Type": "Image",
"Reference": "Result.LVR.LVRLimit[0]",
"URL": "https://storage.googleapis.com/mortgage-rec-engine-dev.appspot.com/lender-guidelines/sbs_PropertyType.jpg"
}
],
"Accuracy": 0.69,
"Version": {
"VersionNumber": "v16.5",
"ReleaseDate": "2025-10-23",
"VersionReleaseNote": ""
},
"SpreadsheetFileURL": "https://api.mre.test.blackfin.tools/engine/download-spreadsheet?report_id=7Z0nc3ZJ&case_id=1&lender=sbs"
},
{
"Lender": {
"Id": 9,
"Key": "tsb",
"Name": "TSB",
"Logo": "https://storage.googleapis.com/mortgage-rec-engine-dev.appspot.com/lender-logos/tsb.png"
},
"Result": {
"AssessedIncome": [
{
"Group": "Applicant Income",
"Label": "Salary and Wage (Gary)",
"Entered": {
"Amount": 85000,
"Frequency": "Annually"
},
"Assessed": {
"Amount": 5471.08,
"Frequency": "Monthly"
}
},
{
"Group": "Applicant Income",
"Label": "Salary and Wage (Lynne)",
"Entered": {
"Amount": 48000,
"Frequency": "Annually"
},
"Assessed": {
"Amount": 3324.2,
"Frequency": "Monthly"
}
}
],
"AssessedExpense": [
{
"Group": "Lending",
"Label": "Proposed Mortgage",
"Entered": {
"Amount": 350000,
"InterestRate": 0.0649
},
"Assessed": {
"Amount": 2209.94,
"Frequency": "Monthly"
}
},
{
"Group": "Lending",
"Label": "Credit Cards",
"Entered": {
"Amount": 10000,
"Definition": "Limit"
},
"Assessed": {
"Amount": 380,
"Frequency": "Monthly"
}
},
{
"Group": "Living Expenses",
"Label": "Insurances (House, Contents, Vehicle, Life, Health)",
"Entered": {
"Amount": 480,
"Frequency": "Monthly"
},
"Assessed": {
"Amount": 480,
"Frequency": "Monthly"
}
},
{
"Group": "Living Expenses",
"Label": "Rates & Water Rates",
"Entered": {
"Amount": 0,
"Frequency": "Monthly"
},
"Assessed": {
"Amount": 230,
"Frequency": "Monthly"
}
},
{
"Group": "Living Expenses",
"Label": "Childcare & Day-Care",
"Entered": {
"Amount": 250,
"Frequency": "Monthly"
},
"Assessed": {
"Amount": 250,
"Frequency": "Monthly"
}
},
{
"Group": "Living Expenses",
"Label": "Food - Groceries",
"Entered": {
"Amount": 700,
"Frequency": "Monthly"
},
"Assessed": {
"Amount": 1236,
"Frequency": "Monthly"
}
},
{
"Group": "Living Expenses",
"Label": "Utilities (Electricity, Gas, Water)",
"Entered": {
"Amount": 400,
"Frequency": "Monthly"
},
"Assessed": {
"Amount": 400,
"Frequency": "Monthly"
}
},
{
"Group": "Living Expenses",
"Label": "Transport (Fuel, WOF, Rego, Public Transport)",
"Entered": {
"Amount": 0,
"Frequency": "Monthly"
},
"Assessed": {
"Amount": 396,
"Frequency": "Monthly"
}
},
{
"Group": "Living Expenses",
"Label": "Personal Expenses (Clothing, Footwear, Personal Care, Spend on Dependants)",
"Entered": {
"Amount": 0,
"Frequency": "Monthly"
},
"Assessed": {
"Amount": 274.5,
"Frequency": "Monthly"
}
},
{
"Group": "Living Expenses",
"Label": "Telecommunications (Landline, Mobile, Internet)",
"Entered": {
"Amount": 0,
"Frequency": "Monthly"
},
"Assessed": {
"Amount": 50,
"Frequency": "Monthly"
}
},
{
"Group": "Living Expenses",
"Label": "Discretionary Living Expenses (Home Improvements, Entertainment, Flights, Pet Care, Subscription TV)",
"Entered": {
"Amount": 100,
"Frequency": "Monthly"
},
"Assessed": {
"Amount": 100,
"Frequency": "Monthly"
}
}
],
"TotalMonthlyIncome": 8795.28,
"TotalMonthlyExpense": 6006.44,
"UMI": {
"Value": 2788.84,
"Required": 0,
"Status": "Pass"
},
"Servicing": {
"Type": "N/A",
"Value": 0,
"Required": 0,
"Status": "Fail"
},
"LVR": [
{
"Reference": "Result.LVR.LVRLimit[0]",
"SecurityId": 1,
"LVRLimit": [
{
"Label": "Property Type",
"Description": "Unknown ",
"MaxLVR": 0.95
}
],
"Value": 0.7,
"RequiredMaxLVR": 0.95,
"Status": "Pass"
}
],
"LEM": [],
"DTI": {
"TotalIncome": 133000,
"TotalDebt": 360000,
"Value": 2.71,
"RequiredMaxDTI": 6,
"Status": "Pass"
},
"Deposit": {
"Amount": 0
},
"MaxLoanAmount": 791600
},
"Warnings": [],
"Errors": [],
"Resources": [
{
"Type": "Image",
"Reference": "Result.LVR.LVRLimit[0]",
"URL": "https://storage.googleapis.com/mortgage-rec-engine-dev.appspot.com/lender-guidelines/tsb_PropertyType.jpg"
},
{
"Type": "Image",
"Reference": "Result.DTI",
"URL": "https://storage.googleapis.com/mortgage-rec-engine-dev.appspot.com/lender-guidelines/tsb_DTI.jpg"
}
],
"Accuracy": 0.69,
"Version": {
"VersionNumber": "v.6.8",
"ReleaseDate": "2025-10-13",
"VersionReleaseNote": ""
},
"SpreadsheetFileURL": "https://api.mre.test.blackfin.tools/engine/download-spreadsheet?report_id=7Z0nc3ZJ&case_id=1&lender=tsb"
},
{
"Lender": {
"Id": 10,
"Key": "westpac",
"Name": "Westpac",
"Logo": "https://storage.googleapis.com/mortgage-rec-engine-dev.appspot.com/lender-logos/westpac.png"
},
"Result": {
"AssessedIncome": [
{
"Group": "Applicant Income",
"Label": "Applicant Income (Gary)",
"Entered": {
"Amount": 5479.28,
"Frequency": "Monthly"
},
"Assessed": {
"Amount": 5479.28,
"Frequency": "Monthly"
}
},
{
"Group": "Applicant Income",
"Label": "Applicant Income (Lynne)",
"Entered": {
"Amount": 3328,
"Frequency": "Monthly"
},
"Assessed": {
"Amount": 3328,
"Frequency": "Monthly"
}
}
],
"AssessedExpense": [
{
"Group": "Lending",
"Label": "New Home Loan",
"Entered": {
"Amount": 350000,
"InterestRate": 0
},
"Assessed": {
"Amount": 2223.76,
"Frequency": "Monthly"
}
},
{
"Group": "Other Liabilities",
"Label": "Credit Card(s)",
"Entered": {
"Amount": 10000,
"Definition": "Limit"
},
"Assessed": {
"Amount": 380,
"Frequency": "Monthly"
}
},
{
"Group": "Fixed Commitments",
"Label": "Personal Insurances",
"Entered": {
"Amount": 480,
"Frequency": "Monthly"
},
"Assessed": {
"Amount": 480,
"Frequency": "Monthly"
}
},
{
"Group": "Essential Living Costs",
"Label": "Essential Living Costs",
"Entered": {
"Amount": 1350,
"Frequency": "Monthly"
},
"Assessed": {
"Amount": 2230,
"Frequency": "Monthly"
}
}
],
"TotalMonthlyIncome": 8807.28,
"TotalMonthlyExpense": 5313.76,
"UMI": {
"Value": 3493.52,
"Required": 150,
"Status": "Pass"
},
"Servicing": {
"Type": "N/A",
"Value": 0,
"Required": 0,
"Status": "Fail"
},
"LVR": [
{
"Reference": "Result.LVR.LVRLimit[0]",
"SecurityId": 1,
"LVRLimit": [
{
"Label": "Property Type",
"Description": "Unknown",
"MaxLVR": 0.9
},
{
"Label": "Usage Type",
"Description": "Unknown",
"MaxLVR": 0.9
}
],
"Value": 0.7,
"RequiredMaxLVR": 0.9,
"Status": "Pass"
}
],
"LEM": [
{
"Label": "Total Lending",
"LoanId": null,
"Assessed": 0.7,
"Margin": 0,
"Amount": null
}
],
"DTI": {
"TotalIncome": 133000,
"TotalDebt": 360000,
"Value": 2.71,
"RequiredMaxDTI": 6,
"Status": "Pass"
},
"Deposit": {
"Amount": 0
},
"MaxLoanAmount": 876200
},
"Warnings": [],
"Errors": [],
"Resources": [
{
"Type": "Image",
"Reference": "Result.LVR.LVRLimit[0]",
"URL": "https://storage.googleapis.com/mortgage-rec-engine-dev.appspot.com/lender-guidelines/westpac_PropertyType.jpg"
},
{
"Type": "Image",
"Reference": "Result.LVR.LVRLimit[1]",
"URL": "https://storage.googleapis.com/mortgage-rec-engine-dev.appspot.com/lender-guidelines/westpac_UsageType.jpg"
},
{
"Type": "Image",
"Reference": "Result.DTI",
"URL": "https://storage.googleapis.com/mortgage-rec-engine-dev.appspot.com/lender-guidelines/westpac_DTI.jpg"
}
],
"Accuracy": 0.69,
"Version": {
"VersionNumber": "v13Oct2025",
"ReleaseDate": "2025-10-13",
"VersionReleaseNote": ""
},
"SpreadsheetFileURL": "https://api.mre.test.blackfin.tools/engine/download-spreadsheet?report_id=7Z0nc3ZJ&case_id=1&lender=westpac"
}
]
}
],
"Accuracy": 0.69
}
}
}Error
If errors are encountered during the Generate Report operation:
JSON Body
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"description": "Error information",
"properties": {
"message": {
"type": "string",
"description": "Human readable error message"
},
"status": {
"type": "string",
"description": "Error code in uppercase letters and _ as space",
"enum": ["INVALID_ARGUMENT","DEADLINE_EXCEEDED","NOT_FOUND","ALREADY_EXISTS","PERMISSION_DENIED","RESOURCE_EXHAUSTED","FAILED_PRECONDITION","ABORTED","OUT_OF_RANGE","UNIMPLEMENTED","INTERNAL","UNAVAILABLE","DATA_LOSS","UNAUTHENTICATED"]
},
"details": {
"type": "object",
"description": "Additional error details",
"properties": {
"validation_errors": {
"type": "array",
"description": "Errors thrown when validating input data",
"items": {
"type": "object",
"properties": {
"path": {
"type": "array",
"description": "An array of property keys or array offsets, indicating where inside objects or arrays the instance was found.",
"items": {
"type": "string"
}
},
"property": {
"type": "string",
"description": "Describes the property path. Starts with `instance`, and is delimited with a dot (.)."
},
"message": {
"type": "string",
"description": "A human-readable message for debugging use. Provided in English and subject to change."
},
"schema": {
"type": "object",
"description": "The schema containing the keyword that failed",
"properties": {
"type": {
"type": "string"
},
"description": {
"type": "string"
}
},
"required": ["type"]
},
"instance": {
"description": "The instance (value) that failed",
"type": ["null", "object"]
},
"name": {
"type": "string",
"description": "The keyword within the schema that failed."
},
"argument": {
"type": "array",
"description": "Provides information about the keyword that failed.",
"items": {
"type": "string"
}
},
"stack": {
"type": "string"
}
}
}
}
}
}
}
}
},
"required": ["path", "property", "message", "schema", "instance", "name", "argument", "stack"]
}Examples
401: Missing API Key
Missing API Key
{
"error": {
"message": "Missing API Key",
"status": "UNAUTHENTICATED"
}
}
401: Invalid API Key
Invalid API Key
{
"error": {
"message": "Invalid API Key",
"status": "UNAUTHENTICATED"
}
}
400: Invalid data
Invalid data
{
"error": {
"message": "Invalid data",
"status": "INVALID_ARGUMENT",
"details": {
"validation_errors": [
{
"path": [
"Details",
"Loan",
0,
"LoanType"
],
"property": "instance.Details.Loan[0].LoanType",
"message": "is not one of enum values: Existing,Proposed",
"schema": {
"type": "string",
"description": "Defines whether the applicant already has this loan or if it's a new loan",
"enum": [
"Existing",
"New"
]
},
"instance": "Proposed",
"name": "enum",
"argument": [
"Existing",
"Proposed"
],
"stack": "instance.Details.Loan[0].LoanType is not one of enum values: Existing,Proposed"
}
]
}
}
}
Invalid data: Invalid LoanId on Liability
Thrown when loan id specified on liability does not match a loan.
{
"error": {
"message": "Invalid data: Invalid LoanId specified on Liability",
"status": "INVALID_ARGUMENT",
"details": {
}
}
}
API Reference
Export report to PDF
The Export Report to PDF endpoint exports a generated mortgage report to PDF format and returns a downloadable PDF file URL.
Request
- Type:
POST - Path:
/engine/export-report-pdf
Endpoint
The Export Report to PDF endpoint can be accessed from the following URLs:
| Environment | Endpoint URL |
| Test | https://api.mre.test.blackfin.tools/engine/export-report-pdf |
| Production | https://api.mre.blackfin.tools/engine/export-report-pdf (NOT LIVE) |
Authentication
An API_Key is required to call this endpoint. HTTP Bearer Token authentication is used.
JSON Schema
The request payload is sent as HTTP JSON body using the following schema:
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"title": "Export Report to PDF Request",
"description": "Request payload for exporting a generated mortgage report to PDF format",
"properties": {
"reportId": {
"type": "string",
"description": "ID of the report to export",
"minLength": 1
},
"lenders": {
"type": "array",
"description": "Array of lender codes to include in the PDF",
"items": {
"type": "string",
"enum": [
"aia",
"anz",
"asb",
"bnz",
"co-op",
"kiwibank",
"liberty",
"sbs",
"tsb",
"westpac"
]
},
"minItems": 1,
"uniqueItems": true
},
"currentLoanAmount": {
"type": "number",
"description": "Optional override for loan amount",
"minimum": 0
},
"includeWarningsErrors": {
"type": "boolean",
"description": "Whether to include warnings and errors in the PDF",
"default": false
},
"notes": {
"type": "string",
"description": "Optional notes to include in the PDF",
"maxLength": 5000
}
},
"required": [
"reportId",
"lenders"
],
"additionalProperties": false
}Examples
Example request payload:
JSON Request Body
{
"reportId": "abc123def456",
"lenders": ["anz", "asb", "westpac"],
"currentLoanAmount": 500000,
"includeWarningsErrors": true,
"notes": "Custom notes for this PDF export"
}
Validation
The API performs validation on the request payload:
reportIdandlendersare required fieldslendersmust be a non-empty array with valid lender codescurrentLoanAmountmust be a positive number if providednotescannot exceed 5000 characters
Response
Success
If the Export Report to PDF completes successfully:
JSON Body
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"title": "Export Report to PDF Response",
"description": "Response payload for the export report to PDF operation",
"properties": {
"url": {
"type": "string",
"description": "Signed download URL for the generated PDF file (valid for 24 hours)",
"format": "uri",
"pattern": "^https://",
"example": "https://storage.googleapis.com/project.appspot.com/pdf_reports/abc123def456.pdf?GoogleAccessId=...&Expires=1691234567&Signature=..."
}
},
"required": [
"url"
],
"additionalProperties": false
}Examples
200: Success
Success Response
{
"url": "https://storage.googleapis.com/project.appspot.com/pdf_reports/abc123def456.pdf?GoogleAccessId=...&Expires=1691234567&Signature=..."
}Error
If errors are encountered during the Export Report to PDF operation:
JSON Body
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"description": "Error information",
"properties": {
"message": {
"type": "string",
"description": "Human readable error message"
},
"status": {
"type": "string",
"description": "Error code in uppercase letters and _ as space",
"enum": ["INVALID_ARGUMENT","NOT_FOUND","INTERNAL_ERROR","METHOD_NOT_ALLOWED","UNAUTHENTICATED"]
}
}
}
}
}Examples
400: Bad Request
Invalid input
{
"error": {
"message": "Invalid input: reportId and lenders are required",
"status": "INVALID_ARGUMENT"
}
}
401: Missing API Key
Missing API Key
{
"error": {
"message": "Missing API Key",
"status": "UNAUTHENTICATED"
}
}
401: Invalid API Key
Invalid API Key
{
"error": {
"message": "Invalid API Key",
"status": "UNAUTHENTICATED"
}
}
404: Report Not Found
Report not found
{
"error": {
"message": "Report not found",
"status": "NOT_FOUND"
}
}
405: Method Not Allowed
Method not allowed
{
"error": {
"message": "Method Not Allowed",
"status": "METHOD_NOT_ALLOWED"
}
}
Internal Server Error
500: Internal Server Error
{
"error": {
"message": "Error generating PDF",
"status": "INTERNAL_ERROR"
}
}
Lenders
In the MRE, lenders are referenced in two places:
- Requesting which lenders should be used in calculation of results
- Assigning a lender to an existing loan or liability within the customer's financial data
Supported lenders for calculation
When requesting calculation via the API, the MRE currently supports the following list of New Zealand lenders within the Lenders parameter of the request payload:
| Code | Name | Default | Status |
aia |
AIA | ✓ | Active |
anz |
ANZ | ✓ | Active |
asb |
ASB | ✓ | Active |
bnz |
BNZ | ✓ | Active |
co-op |
CO-OP | Active | |
kiwibank |
Kiwibank | Active | |
liberty |
Liberty | Active | |
resimac |
Resimac | Deprecated | |
sbs |
SBS | Active | |
select |
Select | Deprecated | |
tsb |
TSB | Active | |
westpac |
Westpac | ✓ | Active |
The Code value should be used when referencing lenders.
Default lenders
If no Lenders are specified, the five 'Default' lenders are used from the table above.
Supported lenders for loans/liabilities
The table below lists all supported lender values for the Loan.Lender and Liability.Lender parameters within the API request payload:
The Code value should be used when referencing lenders.
Property Types
The table below defines the list of accepted values within the Security.PropertyType parameter of the API request payload. This is a hierarchical list, allowing property types to be specified to up to three levels of granularity. This parameter is used to determine
| PropertyType.Name |
PropertyType.Code | ||
| Residential Property | ResidentialProperty |
||
| FreeHold Residential | FreeHoldResidential |
||
| Terraced Housing | TerracedHousing |
||
| Fee Simple / Cross Lease | FeeSimpleCrossLease |
||
| Unit Title | UnitTitle |
||
| Townhouse | Townhouse |
||
| Lifestyle Block | LifestyleBlock |
||
| 0 to 10 ha | 0to10ha |
||
| >10 ha | over10ha |
||
| Leasehold Residential | LeaseholdResidential |
||
| Apartments | Apartments |
||
| Freehold Apartment | FreeholdApartment |
||
| >50sqm | over50sqm |
||
| 40-50sqm | 40to50sqm |
||
| 38-40sqm | 38to40sqm |
||
| <38sqm | under38sqm |
||
| Leasehold Apartment | LeaseholdApartment |
||
| Serviced Apartment | ServicedApartment |
||
| Student Accommodation | StudentAccommodation |
||
| Bedsitter / Studio / Warehouse Apartments | BedsitterStudioWarehouseApartments |
||
| New Build / Construction | NewBuildConstruction |
||
| Fixed Price Contracts | FixedPriceContracts |
||
| Labour Only / Self (Owner) Build | LabourOnlySelfOwnerBuild |
||
| Relocations | Relocations |
||
| Vacant Land | VacantLand |
||
| Serviced Vacant Land | ServicedVacantLand |
||
| Unserviced Vacant Land | UnservicedVacantLand |
||
| Lifestyle without Dwelling | LifestyleWithoutDwelling |
||
| Other | Other |
||
| Multiple dwellings on one title | MultipleDwellingsOnOneTitle |
||
| 3 dwellings | 3Dwellings |
||
| 4 dwellings | 4Dwellings |
||
| 5 dwellings | 5Dwellings |
||
| 6 dwellings | 6Dwellings |
||
| 7 or more dwellings | 7OrMoreDwellings |
||
The Code value should always be used to reference Property Types.
LVR
The property type is key in determining the applicable LVR rules for each lender – particularly their 'Maximum LVR'. The Security.PropertyType can be provided at any level of the above hierarchy, however more granular choices will yield more accurate results.
Proposed Changes
Some of the options in the above list are being used to capture property size more so than type. In a future release, those options will be removed from the Property Type list and will be re-introduced as dedicated parameters accepting more specific numerical values:
- Lifestyle Block – 'Land Size' (ha)
- Apartments – 'Floor Area' (sqm)
- Multiple Dwellings on One Title – 'Dwellings' (#)