Create a session
Creates a new session from provided data.
When successful, returns a SessionID which can be used to load that session in the MRE UI.
Function performs basic validation on the structure of the request payload but does not impose strict rules based on what is required for generating a report. 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 then user is required to fill in the missing bits if needed.
Request
Type: POST
Path: /sessions/create
URL (Test): https://api.mre.test.blackfin.tools/sessions/create
URL (Prod): https://api.mre.blackfin.tools/sessions/create
Request payload is sent as HTTP JSON body.
Authentication
API Key required. HTTP Bearer Token authentication is used.
JSON Payload
{
"$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": {
"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": "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"
},
"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": [
"LoanId",
"LoanType",
"LoanAmount",
"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",
"resimac",
"sbs",
"select",
"tsb",
"westpac"
]
}
}
},
"required": [
"Details",
"Lenders"
]
}Examples
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": []
}
Response
✅ Success
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
Success Response
{
"SessionID": "BYWSw2DTUBuHVMW4ZdhK",
"SessionURL": "https://mre.test.blackfin.tools/?session_id=BYWSw2DTUBuHVMW4ZdhK"
}❌ Error
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
Missing API Key (Status: 401)
{
"error": {
"message": "Missing API Key",
"status": "UNAUTHENTICATED"
}
}
Invalid API Key (Status: 401)
{
"error": {
"message": "Invalid API Key",
"status": "UNAUTHENTICATED"
}
}
Invalid data (Status: 400)
{
"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 specified on Liability (Status: 400)
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": {
}
}
}