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 5-10 seconds to generate a report which consists of 20 different loan amount cases 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#",
"$defs": {
"Lender": {
"type": [
"string",
"null"
],
"description": "The [lender (bank)](https://docs.blackfin.tools/books/mortgagerecenginemycrm/page/lenders) which the existing loan is with/from - eg. 'Westpac' this field is only present if LoanType=Existing",
"enum": [
null,
"AbodeMortgagesLimited",
"AccessHomeLoansLimited",
"Accuro",
"AIA",
"AlliedDunbar",
"AMBL",
"AMPLifetrack",
"AMPRPP",
"ANZ",
"Argosy",
"ASAPFinanceLimited",
"ASB",
"AscendFinance",
"AssetFinanceSelect",
"AsteronLife",
"AvantiFinance",
"BankofChinaNewZealandLimited",
"BasecorpFinance",
"BasecorpFinance",
"Bluestone",
"BNZ",
"CBS",
"CFML",
"ChinaConstructionBankNewZealandLimited",
"Cigna",
"CommixGroupLimited",
"CressidaCapital",
"DBR",
"DBRLimited",
"EconomyHomeLoans",
"FamilyFinance",
"FidelityLife",
"FirstMortgageTrust",
"FreedomMortgages",
"FreedomMortgagesLtd",
"GEMoney",
"GemHomeLoans",
"GeneralFinance",
"GoldBandFinance",
"Greenwich",
"HeartlandBank",
"HeartlandBankONHOLD",
"HomeTrustMortgagesCentralWestLtd",
"HSBC",
"IndustrialandCommercialBankofChinaNewZealandLimited",
"Kiwibank",
"KMMHO",
"LibertyFinancial",
"LibertyFinancialLimited",
"MARAC",
"MetroMoneyLtd",
"MortgageNorth",
"MTF",
"MutualFinanceLimited",
"NationalBank",
"NBS",
"Neo",
"NIB",
"NZFinance",
"NZGuardianTrust",
"NZCUSouth",
"NZF",
"OriginANZ",
"Other",
"OtherLenders",
"OtherNonBankLenders",
"Oxford",
"PacificHomeLoans",
"PacificRetailFinance",
"PartnersLife",
"Pepper",
"PFS",
"PinnacleLife",
"Pioneer",
"Presto",
"PropertyEquityFinance",
"PropertyFinanceSecuritiesLimited",
"PROSPA",
"Provident",
"PublicTrust",
"RESIMAC",
"SBSBank",
"SCF",
"SelectHomeLoan",
"Simplify",
"SouthernCross",
"SouthernCross",
"SouthernCrossBuildingSociety",
"SouthernCrossFinanceLtd",
"Sovereign",
"SuperBank",
"TasmanMortgages",
"TheCooperativeBank",
"Tower",
"TrustUs",
"TSB",
"UDCFinance",
"UnitedHomeLoans",
"Unity",
"Westpac",
"WizardHomeloans",
"XEMoneyTransfer",
"ZipBusiness"
],
"default": null
},
"Frequency": {
"type": "string",
"enum": [
"Yearly",
"HalfYearly",
"Quarterly",
"Monthly",
"Fortnightly",
"Weekly"
]
},
"FrequencyOrNull": {
"type": [
"string",
"null"
],
"enum": [
null,
"Yearly",
"HalfYearly",
"Quarterly",
"Monthly",
"Fortnightly",
"Weekly"
]
}
},
"title": "Request JSON Payload",
"type": "object",
"properties": {
"Details": {
"type": "object",
"description": "Contains details for mortgage calculation",
"properties": {
"Loan": {
"description": "Array of Loan objects",
"type": "array",
"items": {
"type": "object",
"properties": {
"LoanId": {
"type": "integer",
"description": "Numerical identifier for the Loan, typically an incremental ID starting with 1",
"minimum": 1
},
"LoanType": {
"type": "string",
"description": "Defines whether the applicant already has this loan or if it's a new loan",
"enum": [
"Existing",
"New"
]
},
"Lender": {
"$ref": "#/$defs/Lender"
},
"LendingAction": {
"type": [
"string",
"null"
],
"description": "Defines what action the applicant wants to take on an existing loan, only set if LoanType=Existing",
"enum": [
null,
"None",
"Refinance",
"TopUp"
],
"default": null
},
"LiabilityType": {
"type": "string",
"description": "The type of loan being applied for",
"enum": [
"HomeLoan"
],
"default": "HomeLoan"
},
"LoanAmount": {
"type": [
"number"
],
"description": "The amount of the loan (in $) being requested",
"default": null
},
"TopUpAmount": {
"type": [
"number",
"null"
],
"description": "The amount of the 'proposed increase' to the loan (in $) being requested",
"default": null
},
"TotalTermMonths": {
"type": "integer",
"description": "The new loan's overall total term (expressed in months)",
"minimum": 1
},
"InterestOnlyTermMonths": {
"type": "integer",
"description": "The new loan's optional 'Interest-Only' term (expressed in months)",
"minimum": 0,
"default": 0
},
"Security": {
"type": "object",
"description": "Security for the Loan",
"properties": {
"Value": {
"type": "number",
"description": "The value of the property (in $)"
},
"IsRBNZExempt": {
"type": "boolean",
"description": "Inidicates someone who is eligible for 90% lending. Default = false. [See also](https://www.rbnz.govt.nz/regulation-and-supervision/banks/macro-prudential-policy/loan-to-valuation-ratio-restrictions#:~:text=Loans%20to%20people%20building%20a,occupiers%20and%20residential%20property%20investors.)",
"default": false
},
"Location": {
"type": [
"string",
"null"
],
"description": "Address of the property",
"default": null
},
"PropertyType": {
"type": "array",
"description": "Up to three levels of property categorisation. [0] array item is level 1, [1] is level 2, [2] is level 3. See [property type](https://docs.blackfin.tools/books/mortgagerecenginemycrm/page/loan-security-property-types) table",
"items": {
"type": [
"string",
"null"
],
"enum": [
null,
"ResidentialProperty",
"FreeHoldResidential",
"TerracedHousing",
"FeeSimpleCrossLease",
"UnitTitle",
"Townhouse",
"LifestyleBlock",
"0to10ha",
"over10ha",
"LeaseholdResidential",
"Apartments",
"FreeholdApartment",
"over50sqm",
"40to50sqm",
"38to40sqm",
"under38sqm",
"LeaseholdApartment",
"ServicedApartment",
"StudentAccommodation",
"BedsitterStudioWarehouseApartments",
"NewBuildConstruction",
"FixedPriceContracts",
"LabourOnlySelfOwnerBuild",
"Relocations",
"VacantLand",
"ServicedVacantLand",
"UnservicedVacantLand",
"LifestyleWithoutDwelling",
"Other",
"MultipleDwellingsOnOneTitle",
"3Dwellings",
"4Dwellings",
"5Dwellings",
"6Dwellings",
"7OrMoreDwellings"
]
},
"default": []
},
"SecurityType": {
"type": "string",
"description": "Defines whether the Security is already owned by the Applicant or not",
"enum": [
"Existing",
"Proposed"
]
},
"UsageType": {
"type": [
"string",
"null"
],
"description": "How the property will be used - eg. 'Owner Occupied'",
"enum": [
null,
"OwnerOccupied",
"InvestmentProperty"
],
"default": null
},
"ValuationType": {
"type": [
"string",
"null"
],
"description": "The source of the valuation of the property. (Calculation logic coming soon)",
"enum": [
null,
"CouncilValuation",
"EVal",
"FullRegisteredValuation",
"SalePurchaseAgreement"
],
"default": null
}
},
"required": [
"Value",
"SecurityType"
]
}
},
"required": [
"LoanAmount",
"LoanId",
"LoanType",
"TotalTermMonths"
]
}
},
"ApplicantParty": {
"type": "array",
"description": "One or more parties (eg. married couple) who are applying for the home loan",
"items": {
"type": "object",
"properties": {
"Applicant": {
"type": "array",
"description": "One or more individuals belonging to the Applicant Party",
"items": {
"type": "object",
"properties": {
"ApplicantId": {
"type": "integer",
"description": "Numerical identifier for the individual Applicant, typically an incremental ID starting with 1",
"minimum": 1
},
"Name": {
"type": "string",
"description": "Full name of the individual Applicant"
}
},
"required": [
"ApplicantId"
]
}
},
"NumberOfDependents": {
"type": "integer",
"description": "Number of dependents of this applicant party",
"minimum": 0,
"default": 0
},
"NumberOfVehicles": {
"type": "integer",
"description": "Number of owned vehicles by this applicant party",
"minimum": 0,
"default": 0
},
"Expense": {
"type": "array",
"description": "One or more regular expenses being declared by the applicant party",
"items": {
"type": "object",
"properties": {
"ApplicantId": {
"type": "integer",
"description": "The ID of the individual applicant who the expense belongs to",
"minimum": 1
},
"ExpenseType": {
"type": "string",
"description": "The type of expense being declared - eg. 'Groceries'",
"enum": [
"ChildCare",
"ChildMaintenance",
"HigherEducationAndVocationalTraining",
"OtherEducation",
"PrivateSchoolCosts",
"PublicSchoolCosts",
"Groceries",
"OtherGroceries",
"BuildingInsurance",
"ContentsInsurance",
"HealthInsurance",
"IncomeProtection",
"LifeInsurance",
"OtherInsurance",
"VehicleInsurance",
"BodyCorporateInvestmentProperty",
"BuildingInsuranceInvestmentProperty",
"CouncilRatesInvestmentProperty",
"ElectricityAndGasInvestmentProperty",
"OtherInvestmentPropertyExpense",
"RepairsAndMaintenanceInvestmentProperty",
"RunningCostsInvestmentProperty",
"WaterAndSewerInvestmentProperty",
"MedicalAndHealth",
"NaturalTherapies",
"OtherMedical",
"Board",
"OtherOngoingRent",
"Rent",
"Kiwisaver",
"Other",
"RegularDonations",
"VoluntarySaving",
"VoluntarySuper",
"ClothingAndFootwear",
"Cosmetics",
"DryCleaning",
"OtherPersonalCare",
"PersonalCare",
"BodyCorporatePrimaryResidence",
"CouncilRatesPrimaryResidence",
"ElectricityAndGasPrimaryResidence",
"FurnishingsAndElectrical",
"HomeOperation",
"HomeRepairs",
"OtherPrimaryResidenceExpense",
"WaterAndSewerPrimaryResidence",
"AlcoholTobacco",
"CinemaConcertsMemberships",
"DiningOut",
"Gambling",
"Gambling2",
"GiftsAndMiscellaneous",
"GymSports",
"OtherRecreationalAndEntertainment",
"Pets",
"TravelAndHolidays",
"ContentsInsuranceSecondaryResidence",
"BodyCorporateSecondaryResidence",
"BuildingInsuranceSecondaryResidence",
"CouncilRatesSecondaryResidence",
"ElectricityAndGasSecondaryResidence",
"OtherSecondaryResidenceExpense",
"RepairsAndMaintenanceSecondaryResidence",
"RunningCostsSecondaryResidence",
"WaterAndSewerSecondaryResidence",
"HomeMobilePhone",
"InternetPayTVAndMediaStreamingSubscriptions",
"OtherTelephoneAndInternet",
"Petrol",
"PublicTransport",
"Registration",
"TaxiRideSharing",
"TollsParking",
"VehicleMaintenance"
]
},
"Frequency": {
"$ref": "#/$defs/Frequency",
"description": "The frequency with which the applicant pays the expense - eg. 'Weekly'"
},
"Amount": {
"type": "number",
"description": "The amount of the expense (in $)"
}
},
"required": [
"ExpenseType",
"Amount",
"Frequency"
]
},
"default": []
},
"Income": {
"type": "array",
"description": "One or more incomes being declared by the Applicant Party",
"items": {
"type": "object",
"properties": {
"ApplicantId": {
"type": "integer",
"description": "The ID of the individual applicant who the income belongs to",
"minimum": 0
},
"IncomeType": {
"type": "string",
"description": "The type of income being declared - eg. 'Salary'",
"enum": [
"CarAllowance",
"Companycar",
"DisabilityAllowance",
"WorkAllowance",
"Bonus",
"Commission",
"CompanyProfitBeforeTax",
"ChildSupport",
"FamilyAllowance",
"Other",
"UnemployedAllowance",
"WidowAllowance",
"Annuities",
"Dividends",
"Interest",
"OtherIncome",
"OtherNetIncome",
"WorkersCompensation",
"RegularOvertime",
"BoarderIncome",
"RentalIncome",
"ForeignIncome",
"SalaryWages",
"PrivatePension",
"Superannuation"
]
},
"Frequency": {
"$ref": "#/$defs/Frequency",
"description": "The frequency with which the applicant receives the income - eg. 'Monthly'"
},
"Amount": {
"type": "number",
"description": "The amount of the income (in $)"
},
"AmountType": {
"type": "string",
"enum": [
null,
"Gross",
"Net"
],
"description": "Type of income amount - Net or Gross, defaults to Gross",
"default": "Gross"
},
"Attributes": {
"type": "array",
"description": "Additional information about the income",
"items": {
"anyOf": [
{
"title": "Kiwisaver",
"type": "object",
"description": "Kiwisaver (set on SalaryWages)",
"properties": {
"name": {
"const": "Kiwisaver"
},
"value": {
"type": "boolean",
"default": false
}
}
},
{
"title": "KiwisaverContribution",
"type": "object",
"description": "KiwisaverContribution (set on SalaryWages, if Kiwisaver=true)",
"properties": {
"name": {
"const": "KiwisaverContribution"
},
"value": {
"type": "number",
"description": "Percentage value represented as a float - 0.06 for 6% contribution"
}
}
},
{
"title": "PropertyCountry",
"type": "object",
"description": "PropertyCountry (set on RentalIncome)",
"properties": {
"name": {
"const": "PropertyCountry"
},
"value": {
"type": "string",
"enum": [
"NZ",
"Offshore"
]
}
}
},
{
"title": "PropertyBuildDate",
"type": "object",
"description": "PropertyBuildDate (set on RentalIncome)",
"properties": {
"name": {
"const": "PropertyBuildDate"
},
"value": {
"type": "string",
"format": "YYYY-MM-DD",
"description": "Date in ISO format: YYYY-MM-DD"
}
}
},
{
"title": "SalePurchaseDate",
"type": "object",
"description": "SalePurchaseDate (set on RentalIncome)",
"properties": {
"name": {
"const": "SalePurchaseDate"
},
"value": {
"type": "string",
"format": "YYYY-MM-DD",
"description": "Date in ISO format: YYYY-MM-DD"
}
}
},
{
"title": "IsTaxExempt",
"type": "object",
"description": "IsTaxExempt (set on RentalIncome)",
"properties": {
"name": {
"const": "IsTaxExempt"
},
"value": {
"type": "boolean"
}
}
},
{
"title": "BoarderIncomeType",
"type": "object",
"description": "BoarderIncomeType (set on BoarderIncome)",
"properties": {
"name": {
"const": "BoarderIncomeType"
},
"value": {
"type": "string",
"enum": [
"AllInclusive",
"RoomChargeOnly"
]
}
}
}
]
}
}
},
"required": [
"ApplicantId",
"IncomeType",
"Frequency",
"Amount"
]
},
"default": []
},
"Liability": {
"type": "array",
"description": "One or more existing liabilities (debts) being declared by the applicant party.",
"items": {
"type": "object",
"properties": {
"ApplicantId": {
"type": "integer",
"description": "The ID of the individual applicant who the liability belongs to. \n\nRequired when `LiabilityType` is StudentLoan."
},
"LoanId": {
"type": [
"integer",
"null"
],
"description": "The ID of the connected loan"
},
"LiabilityType": {
"type": "string",
"description": "The type of liability being declaired - eg. 'Mortgage' or 'CreditCard'",
"enum": [
"ATOCentrelinkDebt",
"ChargeCard",
"CommercialBill",
"ContingentLiability",
"CourtRuledChildMaintenance",
"CourtRuledOtherDebt",
"CreditCard",
"StudentLoan",
"HirePurchase",
"Lease",
"LineOfCredit",
"LoanAsGuarantor",
"Maintenance",
"Other",
"Loan",
"OutstandingTaxAU",
"Overdraft",
"PersonalLoan",
"CarLoan",
"StoreCard",
"Mortgage",
"HomeLoan",
"BusinessLoan",
"OutstandingTaxNZ",
"BuyNowPayLater"
]
},
"RepaymentAmount": {
"type": [
"number",
"null"
],
"description": "The amount (in $) which is being regularly repaid.\n\nRequired when `LiabilityType` is one of `BuyNowPayLater`, `StudentLoan`, `Overdraft`, `BusinessLoan`, `CarLoan`, `PersonalLoan`, `HomeLoan`, `LineOfCredit`, `LoanAsGuarantor`, `Mortgage`, or `Other`.",
"default": null
},
"RepaymentFrequency": {
"$ref": "#/$defs/FrequencyOrNull",
"description": "The frequency with which the applicant pays the liability - eg. 'Weekly'\n\nRequired when `LiabilityType` is one of `BuyNowPayLater`, `StudentLoan`, `Overdraft`, `BusinessLoan`, `CarLoan`, `PersonalLoan`, `HomeLoan`, `LineOfCredit`, `LoanAsGuarantor`, `Mortgage`, or `Other`."
},
"Limit": {
"type": [
"number",
"null"
],
"description": "The amount of the liability's limi (in $) - eg. the credit card limit.\n\nRequired when `LiabilityType` is one of `BuyNowPayLater` or `Overdraft`",
"default": null
},
"Balance": {
"type": [
"number",
"null"
],
"description": "The amount of the liability's balance (in $) - ie. the remaining amount owed.\n\nRequired when `LiabilityType` is one of `BuyNowPayLater`, `StudentLoan`, `BusinessLoan`, `CarLoan`, `PersonalLoan`, `HomeLoan`, `LineOfCredit`, `LoanAsGuarantor`, `Mortgage`, or `Other`.",
"default": null
},
"InterestRate": {
"type": [
"number",
"null"
],
"description": "The rate of interest being charged (in %) on the liability - eg. 0.05 (=5%).\n\nRequired when `LiabilityType` is one of `HomeLoan`, `LineOfCredit`, `LoanAsGuarantor`, or `Mortgage`.",
"default": null
},
"RepaymentType": {
"type": [
"string",
"null"
],
"enum": [null, "PrincipalInterest", "InterestOnly"],
"description": "The repayment structure - either 'Principal & Interest' (default) or 'Interest Only'",
"default": null
},
"StartDate": {
"type": [
"string",
"null"
],
"format": "YYYY-MM-DD",
"description": "Start date of the loan",
"default": null
},
"TotalTermMonths": {
"type": [
"integer",
"null"
],
"description": "The loan's total term in months.\n\nRequired when `LiabilityType` is one of `HomeLoan`, `LineOfCredit`, `LoanAsGuarantor`, or `Mortgage`. ",
"default": null
},
"InterestOnlyTermMonths": {
"type": [
"integer",
"null"
],
"description": "The loan's interest only total term in months",
"default": null
},
"Lender": {
"$ref": "#/$defs/Lender"
},
"IsRevolvingCredit": {
"type": [
"boolean",
"null"
],
"description": "Indicates whether the liability is a revolving credit",
"default": false
}
},
"required": [
"LiabilityType"
],
"allOf": [
{
"if": {
"properties": {
"LiabilityType": {
"const": "BuyNowPayLater"
}
}
},
"then": {
"required": [
"RepaymentAmount",
"RepaymentFrequency",
"Balance",
"Limit"
],
"properties": {
"RepaymentAmount": {
"type": "number"
},
"RepaymentFrequency": {
"type": "string"
},
"Balance": {
"type": "number"
},
"Limit": {
"type": "number"
}
}
}
},
{
"if": {
"properties": {
"LiabilityType": {
"const": "StudentLoan"
}
}
},
"then": {
"required": [
"ApplicantId",
"RepaymentAmount",
"RepaymentFrequency",
"Balance"
],
"properties": {
"RepaymentAmount": {
"type": "number"
},
"RepaymentFrequency": {
"type": "string"
},
"Balance": {
"type": "number"
}
}
}
},
{
"if": {
"properties": {
"LiabilityType": {
"const": "Overdraft"
}
}
},
"then": {
"required": [
"RepaymentAmount",
"RepaymentFrequency",
"Limit"
],
"properties": {
"RepaymentAmount": {
"type": "number"
},
"RepaymentFrequency": {
"type": "string"
},
"Limit": {
"type": "number"
}
}
}
},
{
"if": {
"properties": {
"LiabilityType": {
"enum": [
"BusinessLoan",
"CarLoan",
"PersonalLoan",
"Other"
]
}
}
},
"then": {
"required": [
"RepaymentAmount",
"RepaymentFrequency",
"Balance"
],
"properties": {
"RepaymentAmount": {
"type": "number"
},
"RepaymentFrequency": {
"type": "string"
},
"Balance": {
"type": "number"
}
}
}
},
{
"if": {
"properties": {
"LiabilityType": {
"enum": [
"HomeLoan",
"LineOfCredit",
"LoanAsGuarantor",
"Mortgage"
]
}
}
},
"then": {
"required": [
"RepaymentAmount",
"RepaymentFrequency",
"Balance",
"InterestRate",
"TotalTermMonths"
],
"properties": {
"RepaymentAmount": {
"type": "number"
},
"RepaymentFrequency": {
"type": "string"
},
"Balance": {
"type": "number"
},
"InterestRate": {
"type": "number"
},
"TotalTermMonths": {
"type": "integer"
}
}
}
}
]
},
"default": []
}
}
}
}
},
"required": [
"Loan",
"ApplicantParty"
]
},
"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",
"resimac",
"sbs",
"select",
"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. ThisSame meansrules thatare aapplied successfullyas createdfor create session doesendpoint, notthis guaranteewill thebe datafixed eventually to throw an error when there is completeinsufficient 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.data.
Response
Success
If the Generate Report completes successfully:
JSON Body
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Response JSON Body",
"type": "object",
"properties": {
"ReportURL": {
"type": "string",
"description": "Fully constructed URL to the generated report PDF.",
"example": "https://mre.test.blackfin.tools/reports/BYWSw2DTUBuHVMW4ZdhK.pdf"
}
}
}Examples
200: Success
Success Response
{
"ReportURL": "https://mre.test.blackfin.tools/reports/BYWSw2DTUBuHVMW4ZdhK.pdf"
}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": {
}
}
}