httpsEngineCreateSession
This function creates a session with a set of inputs and MyCRM user-associated data.
Request
- Type:
POSTinstructions - Path:
/httpsEngineCreateSession
Authentication
HTTP Header Authorization should contain string:
Bearer <API_KEY>
Where <API_KEY> is replaced by an API key provided by the system.
JSON Payload
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Request JSON Payload",
"type": "object",
"properties": {
"MyCRM": {
"type": "object",
"properties": {
"UserID": {
"type": "string",
"description": "MyCRM User ID, used to link MRE session to MyCRM user"
}
},
"required": [
"UserID"
]
},
"Details": {
"type": "object",
"description": "Contains details for mortgage calculation",
"properties": {
"Lenders": {
"type": "array",
"description": "[Lender IDs](https://docs.blackfin.tools/books/mortgagerecenginelenders/page/lenders) to include in calculation. If no Lenders are passed (empty array), the calc will return ASB, ANZ, BNZ, Sovereign and Westpac by default",
"items": {
"type": "string",
"description": "",
"enum": [
"aia",
"anz",
"asb",
"bnz",
"co-op",
"kiwibank",
"resimac",
"sbs",
"select",
"tsb",
"westpac"
]
}
},
"Loan": {
"description": "Array of [Loan](https://docs.blackfin.tools/books/mortgagerecenginebackend/page/loan) objects",
"type": "array",
"items": {
"type": "object",
"properties": {
"LoanId": {
"type": "integer",
"description": "Numerical identifier for the Loan, typically an incremental ID starting with 1"
},
"LoanType": {
"type": "string",
"description": "Defines whether the applicant already has this loan or if it's a new loan",
"enum": [
"Existing",
"Proposed"
]
},
"Lender": {
"type": "string",
"description": "The lender (bank) which the existing loan is with/from - eg. 'Westpac' this field is only present if LoanType=Existing",
"enum": [
"Sovereign",
"AIA",
"Fidelity Life",
"Asteron Life",
"NIB",
"Partners Life",
"Allied Dunbar",
"AMP (Lifetrack)",
"Cigna",
"Accuro",
"AMP (RPP)",
"ASB",
"ANZ",
"National Bank",
"Westpac",
"The Co-operative Bank",
"AMBL",
"Argosy",
"Ascend Finance",
"Avanti Finance",
"Bluestone",
"BNZ",
"CBS",
"DBR Limited",
"Family Finance",
"Freedom Mortgages",
"GE Money",
"Gem Home Loans",
"General Finance",
"Gold Band Finance",
"HSBC",
"Kiwibank",
"KMM H/O",
"Liberty Financial",
"MARAC",
"MTF",
"Mutual Finance Limited",
"NBS",
"NZ Guardian Trust",
"NZF",
"Origin - ANZ",
"Other Lenders",
"Other Non Bank Lenders",
"Pacific Home Loans",
"Pacific Retail Finan",
"PFS",
"Pioneer",
"Presto",
"Property Equity Finanance",
"Public Trust",
"SBS Bank",
"SCF",
"Heartland Bank",
"Southern Cross Building Society",
"Southern Cross Finance Ltd",
"SuperBank",
"Tasman Mortgages",
"TSB",
"United Home Loans",
"Wizard Homeloans",
"Other",
"Access Home Loans Limited",
"Home Trust Mortgages (Central West) Ltd",
"Abode Mortgages Limited",
"Property Finance Securities Limited",
"Mortgage North",
"Metro Money Ltd",
"Freedom Mortgages Ltd",
"Liberty Financial Limited",
"Commix Group Limited",
"NZ Finance",
"ASAP Finance Limited",
"RESIMAC",
"Greenwich",
"Unity",
"Cressida Capital",
"Tower",
"DBR",
"NZCU South",
"Economy Home Loans",
"First Mortgage Trust",
"China Construction Bank (New Zealand) Limited",
"Industrial and Commercial Bank of China (New Zealand) Limited",
"Bank of China (New Zealand) Limited",
"TrustUs",
"Zip Business",
"Simplify",
"XE Money Transfer",
"UDC Finance",
"Oxford",
"Provident",
"Select Home Loan",
"PROSPA",
"Pinnacle Life",
"Asset Finance - Select",
"Southern Cross",
"Basecorp Finance",
"Pepper",
"CFML",
"Neo",
"Heartland Bank (ON HOLD)"
]
},
"LendingAction": {
"type": "string",
"description": "Defines what action the applicant wants to take on an existing loan, only set if LoanType=Existing",
"enum": [
"New",
"Refinance",
"TopUp"
]
},
"LiabilityType": {
"type": "string",
"description": "The type of loan being applied for",
"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"
],
"default": "HomeLoan"
},
"LoanAmount": {
"type": "number",
"description": "The amount of the loan (in $) being requested"
},
"TopUpAmount": {
"type": "number",
"description": "The amount of the 'proposed increase' to the lown (in $) being requested"
},
"TotalTermMonths": {
"type": "integer",
"description": "The new loan's overall total term (expressed in months)"
},
"InterestOnlyTermMonths": {
"type": "integer",
"description": "The new loan's optional 'Interest-Only' term (expressed in months)"
},
"Security": {
"type": "object",
"properties": {
"Value": {
"type": "number",
"description": "The value of the property (in $)"
},
"IsRBNZExempt": {
"type": "null",
"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",
"description": "Address of the property"
},
"PropertyType": {
"type": "array",
"description": "Up to three levels of property categorisation",
"items": {
"type": "string",
"enum": [
"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"
]
}
},
"SecurityType": {
"type": "string",
"description": "Defines whether the Security is already owned by the Applicant or not",
"enum": ["Existing","Proposed"]
},
"UsageType": {
"type": "string",
"description": "How the property will be used - eg. 'Owner Occupied'",
"enum": ["OwnerOccupied", "InvestmentProperty", "OwnerOccupiedNewToBank"]
}
}
}
}
}
},
"ApplicantParty": {
"type": "array",
"description": "Array of [ApplicantParty](https://docs.blackfin.tools/books/mortgagerecenginebackend/page/applicantparty) objects",
"items": {
"type": "object",
"properties": {
"Applicant": {
"type": "array",
"items": {
"type": "object",
"properties": {
"ApplicantId": {
"type": "integer"
},
"Name": {
"type": "string"
}
}
}
},
"Expense": {
"type": "array",
"items": {
"type": "object",
"properties": {
"ApplicantId": {
"type": "integer"
},
"ExpenseType": {
"type": "string"
},
"Frequency": {
"type": "string"
},
"Amount": {
"type": "integer"
}
}
}
},
"Income": {
"type": "array",
"items": {
"type": "object",
"properties": {
"ApplicantId": {
"type": "integer"
},
"IncomeType": {
"type": "string"
},
"Frequency": {
"type": "string"
},
"Amount": {
"type": "integer"
}
}
}
}
}
}
}
},
"required": [
"Lenders",
"Loan",
"ApplicantParty"
]
}
},
"required": [
"Details",
"MyCRM"
]
}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"
}
}
}Examples
Example 1: Success Response
{
"SessionID": "BYWSw2DTUBuHVMW4ZdhK"
}