CalculationRequestPayload
At the core of MRE functionality is generating reports on a calculation request. A calculation request may be sent towards a generate report endpoint, in which case the calculation request is immediately calculated against the engine's logic, or the calculation request is sent to a create session endpoint for the MyCRM integration, in which case that calculation is deferred for later and just stored in the database.
In both of those cases, the calculation request payload is in the same format described below.
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Mortgage Recommendation Engine - Calculation Request Payload",
"description": "Schema for calculation request payload",
"type": "object",
"properties": {
"Details": {
"type": "object",
"description": "Main details object containing loan and applicant party information",
"properties": {
"Loan": {
"type": "array",
"description": "Array of loan objects representing loans being applied for or existing loans",
"items": {
"type": "object",
"properties": {
"LoanId": {
"type": "integer",
"description": "Unique identifier for the loan"
},
"LoanType": {
"type": "string",
"description": "Type of loan",
"enum": ["New", "Existing"]
},
"Lender": {
"type": "string",
"description": "Name of the lender providing the loan"
},
"LendingAction": {
"type": "string",
"description": "Type of lending action",
"enum": ["Purchase", "Refinance", "TopUp", "Construction"]
},
"LiabilityType": {
"type": "string",
"description": "Type of liability/loan",
"enum": ["HomeLoan", "PersonalLoan", "CreditCard", "StudentLoan", "BusinessLoan"]
},
"LoanAmount": {
"type": "number",
"description": "Amount of the loan",
"minimum": 0
},
"TopUpAmount": {
"type": ["number", "null"],
"description": "Additional top-up amount if applicable",
"minimum": 0
},
"TotalTermMonths": {
"type": "integer",
"description": "Total term length of the loan in months",
"minimum": 1
},
"InterestOnlyTermMonths": {
"type": "integer",
"description": "Number of months for interest-only payments",
"minimum": 0
},
"Security": {
"type": "object",
"description": "Security/property details for the loan",
"properties": {
"Value": {
"type": "number",
"description": "Value of the security/property",
"minimum": 0
},
"IsRBNZExempt": {
"type": "boolean",
"description": "Whether the property is RBNZ exempt"
},
"Location": {
"type": ["string", "null"],
"description": "Property location/address"
},
"PropertyType": {
"type": "array",
"description": "Array of property type classifications",
"items": {
"type": "string",
"enum": ["ResidentialProperty", "CommercialProperty", "Rural", "Lifestyle", "TerracedHousing", "UnitTitle", "Apartment", "House", "Townhouse"]
}
},
"SecurityType": {
"type": "string",
"description": "Type of security",
"enum": ["Existing", "New"]
},
"UsageType": {
"type": "string",
"description": "How the property will be used",
"enum": ["OwnerOccupied", "Investment", "Holiday"]
},
"ValuationType": {
"type": ["string", "null"],
"description": "Type of valuation performed"
}
},
"required": ["Value", "IsRBNZExempt", "PropertyType", "SecurityType", "UsageType"]
}
},
"required": ["LoanId", "LoanType", "LiabilityType", "LoanAmount", "TotalTermMonths", "InterestOnlyTermMonths", "Security"]
},
"minItems": 1
},
"ApplicantParty": {
"type": "array",
"description": "Array of applicant party objects (typically one party)",
"items": {
"type": "object",
"properties": {
"Applicant": {
"type": "array",
"description": "Array of individual applicants in the party",
"items": {
"type": "object",
"properties": {
"ApplicantId": {
"type": "integer",
"description": "Unique identifier for the applicant, starting from 1"
},
"Name": {
"type": "string",
"description": "Name of the applicant"
}
},
"required": ["ApplicantId", "Name"]
},
"minItems": 1
},
"Expense": {
"type": "array",
"description": "Array of expense objects for the applicant party",
"items": {
"type": "object",
"properties": {
"ApplicantId": {
"type": ["integer", "null"],
"description": "Reference to specific applicant, or null for shared expenses"
},
"ExpenseType": {
"type": "string",
"description": "Type/category of expense",
"enum": [
"HealthInsurance", "LifeInsurance", "IncomeProtection", "ContentsInsurance", "VehicleInsurance",
"Groceries", "PublicSchoolCosts", "MedicalAndHealth", "ClothingAndFootwear", "Pets",
"DiningOut", "HomeMobilePhone", "Petrol", "VehicleMaintenance", "TravelAndHolidays",
"Registration", "PersonalCare", "Other", "Kiwisaver", "Rent", "Board", "ElectricityAndGasPrimaryResidence",
"CouncilRates", "PublicTransport", "Childcare", "BodyCorporatePrimaryResidence", "ChildMaintenance",
"VoluntarySaving"
]
},
"Frequency": {
"type": "string",
"description": "Frequency of the expense",
"enum": ["Weekly", "Fortnightly", "Monthly", "Quarterly", "HalfYearly", "Yearly"]
},
"Amount": {
"type": "number",
"description": "Amount of the expense",
"minimum": 0
}
},
"required": ["ExpenseType", "Frequency", "Amount"]
}
},
"Income": {
"type": "array",
"description": "Array of income objects for the applicant party",
"items": {
"type": "object",
"properties": {
"ApplicantId": {
"type": ["integer", "null"],
"description": "Reference to specific applicant, or null for shared income"
},
"IncomeType": {
"type": "string",
"description": "Type/category of income",
"enum": [
"SalaryWages", "OtherIncome", "RentalIncome", "BoarderIncome", "Annuities", "ChildSupport",
"FamilyAllowance", "AirBnBHolidayHome", "BusinessIncome", "CommissionIncome", "BonusIncome",
"OvertimeIncome", "DividendIncome", "InterestIncome", "PensionIncome", "BenefitIncome"
]
},
"Frequency": {
"type": "string",
"description": "Frequency of the income",
"enum": ["Weekly", "Fortnightly", "Monthly", "Quarterly", "HalfYearly", "Yearly", "Annually"]
},
"Amount": {
"type": "number",
"description": "Amount of the income",
"minimum": 0
},
"AmountType": {
"type": "string",
"description": "Whether the amount is gross or net",
"enum": ["Gross", "Net"]
},
"Attributes": {
"type": "array",
"description": "Additional attributes that further define the income",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Name of the attribute",
"enum": [
"PropertyCountry", "IsTaxExempt", "PropertyBuildDate", "BoarderIncomeType"
]
},
"value": {
"type": ["string", "boolean"],
"description": "Value of the attribute"
}
},
"required": ["name", "value"]
}
}
},
"required": ["IncomeType", "Frequency", "Amount", "AmountType", "Attributes"]
}
},
"Liability": {
"type": "array",
"description": "Array of existing liability objects for the applicant party",
"items": {
"type": "object",
"properties": {
"ApplicantId": {
"type": ["integer", "null"],
"description": "Reference to specific applicant, or null for shared liabilities"
},
"LoanId": {
"type": ["integer", "null"],
"description": "Reference to associated loan if applicable"
},
"LiabilityType": {
"type": "string",
"description": "Type of liability",
"enum": ["CreditCard", "Mortgage", "PersonalLoan", "StudentLoan", "BusinessLoan", "HomeLoan"]
},
"RepaymentAmount": {
"type": "number",
"description": "Regular repayment amount",
"minimum": 0
},
"RepaymentFrequency": {
"type": "string",
"description": "Frequency of repayments",
"enum": ["Weekly", "Fortnightly", "Monthly", "Quarterly", "HalfYearly", "Yearly"]
},
"Limit": {
"type": "number",
"description": "Credit limit or original loan amount",
"minimum": 0
},
"Balance": {
"type": "number",
"description": "Current outstanding balance",
"minimum": 0
},
"InterestRate": {
"type": "number",
"description": "Interest rate as a decimal (e.g., 0.05 for 5%)",
"minimum": 0,
"maximum": 1
},
"RepaymentType": {
"type": "string",
"description": "Type of repayment structure",
"enum": ["PrincipalInterest", "InterestOnly"]
},
"StartDate": {
"type": ["string", "null"],
"description": "Start date of the liability in ISO format (YYYY-MM-DD)",
"format": "date"
},
"TotalTermMonths": {
"type": "integer",
"description": "Total term of the liability in months",
"minimum": 1
},
"InterestOnlyTermMonths": {
"type": "integer",
"description": "Interest-only period in months",
"minimum": 0
},
"Lender": {
"type": "string",
"description": "Name of the lender"
},
"IsRevolvingCredit": {
"type": "boolean",
"description": "Whether this is a revolving credit facility"
}
},
"required": ["LiabilityType", "RepaymentAmount", "RepaymentFrequency", "Limit", "Balance", "InterestRate", "RepaymentType", "TotalTermMonths", "InterestOnlyTermMonths", "Lender", "IsRevolvingCredit"]
}
},
"NumberOfDependents": {
"type": "integer",
"description": "Number of dependents in the applicant party",
"minimum": 0
},
"NumberOfVehicles": {
"type": "integer",
"description": "Number of vehicles owned by the applicant party",
"minimum": 0
}
},
"required": ["Applicant", "Expense", "Income", "Liability", "NumberOfDependents", "NumberOfVehicles"]
},
"minItems": 1
},
"IntendedLVR": {
"type": "number",
"description": "Intended Loan-to-Value Ratio",
"minimum": 0,
"maximum": 1
}
},
"required": ["Loan", "ApplicantParty"]
},
"Lenders": {
"type": "string",
"description": "Comma-separated list of lender codes to include in the calculation",
"pattern": "^[a-z,-]+$",
"examples": ["anz,asb,bnz,co-op,kiwibank,liberty,sbs,tsb,westpac"]
}
},
"required": ["Details", "Lenders"],
"additionalProperties": false
}