Mortgage Origination Optimisation API
The Mortgage Origination Optimisation model can be accessed via an API to integrate the capabilities in external systems.
Standard Endpoint
To generate mortgages compositions from the model Instance use the following POST request endpoint:
https://2jaudpuyo4.execute-api.eu-west-2.amazonaws.com/Prod/generate/origination-mortgage
Request Body
The request body has 11 top level attributes
Table 1: Request Top level attributes
| Attribute Key | Attribute Value description |
| propertyPrice | NUMBER The total value of the property being purchased with the mortgage |
| income | NUMBER The total income of the customers applying for the mortgage |
| maxDeposit | NUMBER The maximum amount of deposit capital the customer has |
| maxMonthlyPayment | NUMBER the maximum amount the customers (or the bank) can pay back every month |
| maxTermLength | NUMBER The maximum amount of year the mortgage repayments can be spread over |
| mortgageTypes | [ STRING ] The types of mortgages the customer is looking for |
| maxLoanAmount |
Number The maximum loan amount being asked for |
| fixedInterestTerms |
[ INTEGER ONLY ] An array of fixed interest terms in years |
| questions | paymentOptions STRING - How do you intend to repay the mortgage "Resale of Property", "Investment", "Savings" - certaintyOrFlexibility STRING - Is budgetary certainty more important to you or flexibility to repay at any time: "Certainty", "Flexibility" - overpayments BOOLEAN - Are you planning to overpay your borrowing in the foreseeable future ? - interestRateViews STRING - What are your views on how interest rates could change and the impact it may have on your monthly payments ? open String |
| legalEntityIdParam |
STRING a query param to be appended to the MCMS query to retrieve the products for a particular legal entity ID. |
| key | STRING The access key to the service |
An example request body:
{
"propertyPrice": 100000,
"income": 25000,
"maxDeposit": 40000,
"maxMonthlyPayment": 500,
"maxTermLength": 25,
"mortgageTypes": ["Annuity", "Linear"],
"maxLoanAmount": 60000,
"fixedInterestTerms": [2, 5],
"questions": {
"paymentOption": "Savings",
"certaintyOrFlexibility": "Certainty",
"overpayments": false,
"interestRateViews": "Go up"
},
"legalEntityIdParam": "legalEntityId=GB0000000",
"key": "AAAAAAAA11111111"
}
Response Body
The response body has 2 top level attributes
Table 2: Response Top level attributes
| Attribute Key | Attribute Value description |
| message | String Informative message about the success-fullness of the request |
| results | [ Mortgage Response Object ] A list of mortgage compositions found to meet the requirements |
| |
The mortgage response objects have 12 top level attributes
Table 3: Mortgage Response attributes
| Attribute Key | Attribute Value description |
| uuid | UUID Unique ID of the solution (used in the model to avoid duplicates) |
| initialMonthlyPayment | NUMBER The monthly payment amount the customer will pay at the start of the mortgage |
| totalDeposit | NUMBER The total deposit amount required for the mortgage |
| avgInterestRate | NUMBER The average interest rate of all the mortgage components |
| avgPeriod | NUMBER The average period (IN MONTHS) for the different mortgage components. i.e. the length of the mortgage |
| totalLoanAmount | NUMBER The total amount being borrowed in the mortgage agreement |
| mortgageTypes | [ STRING ] The mortgage types being used in the mortgage components (! MCMS does not supply this against the product !) |
| productIds | [ STRING ] The list product IDs retrieved from MCMS and used in the mortgage composition |
| totalRepayableValue | NUMBER the total amount to be repaid over the lifetime of the mortgage |
| totalCharges |
NUMBER the total charges associated with the mortgage products |
| description | STRING A list if reasons (separated by | ) as to what distinguishes this mortgage compositions from the others in the list |
| mortgagePartitions | [ Mortgage Objects ] A list of mortgage components that make up the mortgage offer. These contain the decomposed values |
An example response body:
{
"message": "Successfully found results",
"results": [
{
"uuid": "6baffc84-1f8f-442d-97f4-3cdfa5e65fc8",
"initialMonthlyPayment": 342.07,
"totalDeposit": 40000,
"avgInterestRate": 4.75,
"avgPeriod": 300,
"totalLoanAmount": 60000,
"mortgageTypes": [
"Annuity",
"Linear"
],
"productIds": [
"PR21334YJQK6"
],
"fixedInterestTerms": [
2,
5
],
"totalRepayableValue": 102622,
"totalCharges": 400,
"description": "Best Interest Rate|Best Total Repayable Value|Smallest Monthly Payment",
"mortgagePartitions": [
{
"monthlyPayment": 153.93,
"deposit": 18000,
"interestRate": 4.75,
"period": 300,
"splitOfTotalMortgage": 0.45,
"loanAmount": 27000,
"mortgageType": "Linear",
"productId": "PR21334YJQK6",
"totalRepayableValue": 46180,
"charges": 200,
"fixedInterestTerm": 2,
"key": "Part 1"
},
{
"monthlyPayment": 188.14,
"deposit": 22000,
"interestRate": 4.75,
"period": 300,
"splitOfTotalMortgage": 0.55,
"loanAmount": 33000,
"mortgageType": "Annuity",
"productId": "PR21334YJQK6",
"totalRepayableValue": 56442,
"charges": 200,
"fixedInterestTerm": 5,
"key": "Part 2"
}
]
},
{
"uuid": "1971d6db-f3bf-4839-84d2-a44fb6585220",
"initialMonthlyPayment": 377.46,
"totalDeposit": 15000,
"avgInterestRate": 5.75,
"avgPeriod": 300,
"totalLoanAmount": 60000,
"mortgageTypes": [
"Linear"
],
"productIds": [
"PR21334YJQK6"
],
"fixedInterestTerms": [
2
],
"totalRepayableValue": 113239,
"totalCharges": 200,
"description": "Smallest Deposit|Largest Loan Amount",
"mortgagePartitions": [
{
"monthlyPayment": 377.46,
"deposit": 15000,
"interestRate": 5.75,
"period": 300,
"splitOfTotalMortgage": 1,
"loanAmount": 60000,
"mortgageType": "Linear",
"productId": "PR21334YJQK6",
"totalRepayableValue": 113239,
"charges": 200,
"fixedInterestTerm": 2,
"key": "Part 1"
}
]
}
]
}
Simulation Endpoint
To generate mortgages compositions from the model Instance use the following POST request endpoint:
https://2jaudpuyo4.execute-api.eu-west-2.amazonaws.com/Prod/generate/origination-mortgage/simulation
Request Body
The request body REQUIRES the 11 top level attributes from table 1.
It also REQUIRES an additional attributes called mortgagePartitions , this object has 11 attributes. These values should all come from the response of the standard endpoint, EXCEPT the values that are modified. This values can be changed but the modify flag must be set to true
Table 4: SIMULATION mortgage partition attributes
| Attribute Key | Attribute Value description |
| monthlyPayment | FLAG OBJECT {modify: BOOLEAN, value: NUMBER} The monthly payment value, the simulation will try not to exceed this value |
| deposit | FLAG OBJECT {modify: BOOLEAN, value: NUMBER} The deposit value, the simulation will try not to exceed this value |
| period | FLAG OBJECT {modify: BOOLEAN, value: NUMBER} The number of years (mortgage term), the simulation will try not to exceed this value |
| loanAmount | FLAG OBJECT {modify: BOOLEAN, value: NUMBER} The loan value, the simulation will try not to exceed this value |
| mortgageType | FLAG OBJECT {modify: BOOLEAN, value: STRING} The mortgage type to use in this component |
| fixedInterestTerm | FLAG OBJECT {modify: BOOLEAN, value: NUMBER} The fixed interest term to use in this component |
| interestRate | NUMBER The interest rate of the mortgage component |
| productId | STRING The product ID retrieved from MCMS and used in the mortgage composition |
| totalRepayableValue | NUMBER the total amount to be repaid over the lifetime of the mortgage |
| outstandingLoan |
BOOLEAN if this is the outstanding loan amount (For Remortgage Cases), this should be true, else false or not included |
| charges | NUMBER the total charges associated with the mortgage product |
An example request body:
{
"propertyPrice": 100000,
"income": 25000,
"maxDeposit": 40000,
"maxMonthlyPayment": 300,
"maxTermLength": 25,
"mortgageTypes": [
"Annuity",
"Linear"
],
"maxLoanAmount": 65000,
"fixedInterestTerms": [
2,
5
],
"key": "k5b2FDrN6vMCz84E",
"questions": {
"paymentOption": "Savings",
"certaintyOrFlexibility": "Certainty",
"overpayments": false,
"interestRateViews": "Go up"
},
"mortgagePartitions": [
{
"monthlyPayment": {
"modify": false,
"value": 153.93
},
"deposit": {
"modify": false,
"value": 18000
},
"period": {
"modify": false,
"value": 25
},
"loanAmount": {
"modify": true,
"value": 30000
},
"mortgageType": {
"modify": false,
"value": "Annuity"
},
"fixedInterestTerm": {
"modify": false,
"value": 5
},
"interestRate": 4.75,
"productId": "PR21334YJQK6",
"totalRepayableValue": 46180,
"charges": 200,
"key": "Part 1"
},
{
"monthlyPayment": {
"modify": false,
"value": 188.14
},
"deposit": {
"modify": false,
"value": 22000
},
"period": {
"modify": false,
"value": 25
},
"loanAmount": {
"modify": false,
"value": 33000
},
"mortgageType": {
"modify": false,
"value": "Linear"
},
"fixedInterestTerm": {
"modify": false,
"value": 2
},
"interestRate": 4.75,
"productId": "PR21334YJQK6",
"totalRepayableValue": 56442,
"charges": 200,
"key": "Part 2"
}
]
}
Response Body
An example response body:
NOTE: ANY WARNINGS WILL BE APPENDED TO THE MESSAGE ATTRIBUTE
{
"message": "Successfully found results|Max monthly repayment exceeds the requested max monthly repayment ",
"results": [
{
"uuid": "d0b71c7f-55f1-40f1-b036-c5eb7ec9a5cc",
"initialMonthlyPayment": 359.18,
"totalDeposit": 40000,
"avgInterestRate": 4.75,
"avgPeriod": 25,
"totalLoanAmount": 63000,
"mortgageTypes": [
"Annuity",
"Linear"
],
"productIds": [
"PR21334YJQK6"
],
"fixedInterestTerms": [
2,
5
],
"totalRepayableValue": 107753,
"totalCharges": 400,
"description": "Simulation Result",
"mortgagePartitions": [
{
"monthlyPayment": 171.04,
"deposit": 18000,
"interestRate": 4.75,
"period": 25,
"splitOfTotalMortgage": 0.48,
"loanAmount": 30000,
"mortgageType": "Annuity",
"productId": "PR21334YJQK6",
"totalRepayableValue": 51311,
"charges": 200,
"fixedInterestTerm": 5,
"key": "Part 1"
},
{
"monthlyPayment": 188.14,
"deposit": 22000,
"interestRate": 4.75,
"period": 25,
"splitOfTotalMortgage": 0.52,
"loanAmount": 33000,
"mortgageType": "Linear",
"productId": "PR21334YJQK6",
"totalRepayableValue": 56442,
"charges": 200,
"fixedInterestTerm": 2,
"key": "Part 2"
}
]
}
]
}
Remortgage Endpoint
To generate remortgages compositions from the model Instance use the following POST request endpoint:
https://2jaudpuyo4.execute-api.eu-west-2.amazonaws.com/Prod/generate/origination-mortgage/remortgage
Request Body
The request body has 9 top level attributes
Table 1: Request Top level attributes
| Attribute Key | Attribute Value description |
| propertyPrice | NUMBER The total value of the property being purchased with the mortgage |
| income | NUMBER The total income of the customers applying for the mortgage |
| maxMonthlyPayment | NUMBER the maximum amount the customers (or the bank) can pay back every month |
| maxTermLength | NUMBER The maximum amount of year the mortgage repayments can be spread over |
| mortgageTypes | [ STRING ] The types of mortgages the customer is looking for |
| outstandingLoanAmount | Number The existing loan amount the customer has for the property |
| additionalLoanAmount | Number The additional borrowing the customer wishes to add to their existing loan |
| fixedInterestTerms | [ INTEGER ONLY ] An array of fixed interest terms in years |
| questions | paymentOptions STRING - How do you intend to repay the mortgage "Resale of Property", "Investment", "Savings" - certaintyOrFlexibility STRING - Is budgetary certainty more important to you or flexibility to repay at any time: "Certainty", "Flexibility" - overpayments BOOLEAN - Are you planning to overpay your borrowing in the foreseeable future ? - interestRateViews STRING - What are your views on how interest rates could change and the impact it may have on your monthly payments ? open String |
| legalEntityIdParam |
STRING a query param to be appended to the MCMS query to retrieve the products for a particular legal entity ID. |
| key | STRING The access key to the service |
An example request body:
{
"propertyPrice": 200000,
"income": 50000,
"maxMonthlyPayment": 10000,
"maxTermLength": 30,
"mortgageTypes": ["Annuity", "Linear", "Interest only"],
"outstandingLoanAmount": 75000,
"additionalLoanAmount": 25000,
"fixedInterestTerms": [2, 5],
"questions": {
"paymentOption": "Savings",
"certaintyOrFlexibility": "Certainty",
"overpayments": false,
"interestRateViews": "Go up"
},
"legalEntityIdParam": "legalEntityId=GB0000000",
"key": "AAAAAAAA11111111"
}