{"swagger":"2.0","info":{"description":"The Budget Planner API helps to define expenses in retirement. This API consists of two parts (calls). The first call is optional, returning the budget items and typical high/average/low net annual spend for each one. The second call enters the value selected for each of the budget items, calculates the net annual amount needed to meet these, and from this the gross amount that would need to be withdrawn based on current income tax bands and rates. Please refer to the Pricing Plan and the Credits Plan for the number of credits required to call this API.","version":"1.0.0","title":"BudgetPlannerRetirement","contact":{"name":"EValue Support","url":"https://www.ev.uk","email":"support@ev.uk"}},"schemes":["https","http"],"consumes":["application/json"],"produces":["application/json"],"paths":{"/budgetPlannerRetirement/getBudgetParams":{"get":{"summary":"","description":"","operationId":"getBudgetParams","produces":["application/json"],"parameters":[],"responses":{"200":{"description":"successful operation","schema":{"$ref":"#/definitions/BudgetPlannerDataResponse"}},"500":{"description":"System error","schema":{"$ref":"#/definitions/SystemError"}}},"x-auth-type":"Application & Application User","x-throttling-tier":"Unlimited"}},"/budgetPlannerRetirement/calculateTarget":{"post":{"summary":"","description":"","operationId":"calculate","produces":["application/json"],"parameters":[{"in":"body","name":"body","description":"The parameters required to calculate the gross target that will meet the budget in retirement","required":true,"schema":{"$ref":"#/definitions/BudgetIncomePlannerParameters"}}],"responses":{"200":{"description":"successful operation","schema":{"$ref":"#/definitions/BudgetPlannerTargetResponse"}},"400":{"description":"Validation errors","schema":{"$ref":"#/definitions/ValidationErrors"}},"500":{"description":"System error","schema":{"$ref":"#/definitions/SystemError"}}},"x-auth-type":"Application & Application User","x-throttling-tier":"Unlimited"}},"/budgetPlannerRetirement/getPlsaParams":{"get":{"summary":"","description":"","operationId":"getPlsaParams","produces":["application/json"],"parameters":[],"responses":{"200":{"description":"successful operation","schema":{"$ref":"#/definitions/BudgetPlannerPlsaDataResponse"}},"500":{"description":"System error","schema":{"$ref":"#/definitions/SystemError"}}},"x-auth-type":"Application & Application User","x-throttling-tier":"Unlimited"}},"/budgetPlannerRetirement/calculatePlsaTarget":{"post":{"summary":"","description":"","operationId":"calculatePlsa","produces":["application/json"],"parameters":[{"in":"body","name":"body","description":"The parameters required to calculate the gross target that will meet the budget in retirement","required":true,"schema":{"$ref":"#/definitions/BudgetPlsaTargetParameters"}}],"responses":{"200":{"description":"successful operation","schema":{"$ref":"#/definitions/BudgetPlsaTargetResponse"}},"400":{"description":"Validation errors","schema":{"$ref":"#/definitions/ValidationErrors"}},"500":{"description":"System error","schema":{"$ref":"#/definitions/SystemError"}}},"x-auth-type":"Application & Application User","x-throttling-tier":"Unlimited"}}},"definitions":{"Budget":{"type":"object","properties":{"demographic":{"type":"string","description":"The demographic for which these expenses apply"},"marriageStatus":{"type":"string","description":"The marital status for which these expenses apply"},"budgets":{"type":"array","description":"List of standard net expenses that could be used to set target incomes in retirement","items":{"$ref":"#/definitions/BudgetItem"}}}},"BudgetDataItem":{"type":"object","required":["group","id","selectedCost"],"properties":{"id":{"type":"integer","format":"int32","description":"The numerical identifier of the expense being entered","minimum":1,"maximum":100},"group":{"type":"string","description":"The category that the expense belongs to","enum":["ESSENTIALS","DESIRABLES","LUXURIES"]},"selectedCost":{"type":"number","format":"double","description":"The annual net expense required","minimum":0,"maximum":10000000}}},"BudgetIncomePlannerParameters":{"type":"object","required":["budgets"],"properties":{"budgets":{"type":"array","example":[{"id":1,"group":"ESSENTIALS","selectedCost":3911},{"id":2,"group":"ESSENTIALS","selectedCost":911},{"id":3,"group":"ESSENTIALS","selectedCost":6038},{"id":4,"group":"ESSENTIALS","selectedCost":1309},{"id":5,"group":"ESSENTIALS","selectedCost":464},{"id":6,"group":"DESIRABLES","selectedCost":200},{"id":7,"group":"DESIRABLES","selectedCost":3504},{"id":8,"group":"DESIRABLES","selectedCost":2706},{"id":9,"group":"DESIRABLES","selectedCost":6153},{"id":10,"group":"DESIRABLES","selectedCost":1000},{"id":11,"group":"LUXURIES","selectedCost":1121},{"id":12,"group":"LUXURIES","selectedCost":1470},{"id":13,"group":"LUXURIES","selectedCost":2675},{"id":14,"group":"LUXURIES","selectedCost":636},{"id":15,"group":"LUXURIES","selectedCost":4000}],"description":"List of all the expenses due in retirement","items":{"$ref":"#/definitions/BudgetDataItem"}}}},"BudgetItem":{"type":"object","properties":{"id":{"type":"integer","format":"int32","description":"The numerical identifier of the expense being entered"},"name":{"type":"string","description":"The name of the expense"},"minimum":{"description":"A minimum lifestyle that covers all your needs, with some left over for fun","$ref":"#/definitions/BudgetItemLifestyle"},"moderate":{"description":"A moderate lifestyle that allows more financial security and flexibility","$ref":"#/definitions/BudgetItemLifestyle"},"comfortable":{"description":"A comfortable lifestyle that allows more financial freedom and some luxuries","$ref":"#/definitions/BudgetItemLifestyle"}}},"BudgetItemLifestyle":{"type":"object","properties":{"value":{"type":"number","format":"double","description":"The value of the expense"},"summary":{"type":"string","description":"The summary of the expense"},"description":{"type":"string","description":"A detailed description of what the expense allows"}}},"BudgetPlannerDataItem":{"type":"object","required":["group","id"],"properties":{"id":{"type":"integer","format":"int32","description":"The numerical identifier of the expense being entered","minimum":1,"maximum":100},"group":{"type":"string","description":"The category that the expense belongs to","enum":["ESSENTIALS","DESIRABLES","LUXURIES"]},"name":{"type":"string","description":"The name of the expense"},"example":{"type":"string","description":"A basic example of what could be included in the expense"},"furtherInfo":{"type":"string","description":"Further details of the expense"},"high":{"type":"number","format":"double","description":"The annual net target that represents a high cost for this expense"},"average":{"type":"number","format":"double","description":"The annual net target that represents an average cost for this expense"},"low":{"type":"number","format":"double","description":"The annual net target that represents a low cost for this expense"}}},"BudgetPlannerDataResponse":{"type":"object","properties":{"budgets":{"type":"array","description":"List of standard net expenses that could be used to set target incomes in retirement","items":{"$ref":"#/definitions/BudgetPlannerDataItem"}}}},"BudgetPlannerPlsaDataResponse":{"type":"object","properties":{"budgets":{"type":"array","example":[{"demographic":"Outside London","marriageStatus":"Single","budgets":[{"id":1,"name":"Total","minimum":{"value":10232,"summary":"Covers all your needs, with some left over for fun.","description":"A 'minimum' lifestyle covers all your needs, with some left over for fun and social occasions. You could holiday in the UK, eat out about once a month and do some affordable leisure activities about twice a week. About three quarters of employees are likely to achieve at least the minimum standard."},"moderate":{"value":20211,"summary":"More financial security and flexibility.","description":"A 'moderate' lifestyle provides more financial security and more flexibility. You could have one foreign holiday a year and eat out a few times a month. You'd have the opportunity to do more of the things you want to do. Around half of employees are projected to have an income between minimum and moderate."},"comfortable":{"value":33039,"summary":"More financial freedom and some luxuries.","description":"A lifestyle that allows you to be more spontaneous with your money. You could have a subscription to a streaming service, regular beauty treatments and two foreign holidays a year. About one in six employees are projected to have an income between moderate and comfortable."}},{"id":2,"name":"House","minimum":{"value":2576,"summary":"DIY maintenance and decorating one room a year.","description":"Bills and insurance paid, with a budget of £2576 a year for DIY decorating and maintenance. Economy brand appliances."},"moderate":{"value":4110,"summary":"Some help with maintenance and decorating each year.","description":"Boiler servicing and cover plan. £4110 a year for decorating and maintenance with some professional help."},"comfortable":{"value":8805,"summary":"Replace kitchen and bathroom every 10/15 years.","description":"Boiler servicing and cover plan. £8805 a year for professional decorating and maintenance. Weekly lawn cutting and occasional help with gardening and occasional deep cleaning."}},{"id":3,"name":"Food & drink","minimum":{"value":2664,"summary":"A £51 weekly food shop.","description":"An inexpensive meal out once a month, as well as one or two cheaper takeaway meals. A £51 weekly food shop at a mainstream supermarket, with mainly supermarket own label goods. A £4 bottle of wine and standard lager every week."},"moderate":{"value":3791,"summary":"A £73 weekly food shop.","description":"Dine out at a restaurant about once a month, as well one or two takeaway meals. A £73 weekly food shop at a mainstream supermarket with 50% branded goods. A £6 bottle of wine and craft beer."},"comfortable":{"value":7351,"summary":"A £141 weekly food shop.","description":"Dine out at a restaurant about once a week, as well the odd takeaway meal each month. £100 per month to treat others to a meal out. A £141 weekly food shop with 75% branded goods. An £8 bottle of wine and craft beer."}},{"id":4,"name":"Transport","minimum":{"value":1230,"summary":"No car.","description":"Use your free bus pass for most journeys, and £24 per week per household for taxi journeys. £100 a year for rail journeys for visiting friends and family, using senior rail card."},"moderate":{"value":3508,"summary":"3-year old car replaced every 10 years.","description":"A single car per household (three years old, replaced every 10 years). One or two longer distance train journeys to visit friends and family. £67 per week per household for taxi journeys"},"comfortable":{"value":3671,"summary":"2-year old car replaced every five years.","description":"A two-year old mid-range SUV or estate replaced every five years. £200 a year for longer distance train journeys to visit friends and family plus a railcard. Taxi journeys of £71 a week per household."}},{"id":5,"name":"Holidays & Leisure","minimum":{"value":2330,"summary":"A week and a long weekend in the UK every year.","description":"About £250 for one seven-night, half-board coach holiday, plus £150 spending money, and a long weekend by rail and B&B accommodation, both in the UK. Basic TV and broadband. £20 a week for one or two leisure activities."},"moderate":{"value":6212,"summary":"2 weeks in Europe and a long weekend in the UK every year.","description":"About £1,100 for a 7-10 night holiday abroad each year and £200 spending money, and a long weekend in the UK with B&B accomodation. £60 monthly TV and internet subscription, two weekly activities (e.g. cinema, swimming) totalling £35 per week."},"comfortable":{"value":9197,"summary":"3 weeks in Europe every year.","description":"A summer and winter 3* or 4* half board hotel break abroad, for three weeks in total, for around £2,500 a year. Three weekly activities (e.g. cinema, gym class) totalling £50 per week. £60 monthly TV and internet subscription, plus £5.99 for a streaming service."}},{"id":6,"name":"Clothing & Personal","minimum":{"value":466,"summary":"£466 for clothing and footwear each year.","description":"£350 a year on clothes and £110 for shoes. £15 dry haircut every six weeks, NHS dental care and mid-range glasses."},"moderate":{"value":748,"summary":"£748 for clothing and footwear each year.","description":"£500 a year for clothes and £250 for footwear. £35 cut and blow dry and £10 colour every six weeks. NHS dental care and mid-range glasses."},"comfortable":{"value":1496,"summary":"£1,000 - £1,500 for clothing and footwear each year.","description":"£1,000 a year for clothes and £500 a year for shoes. £75 cut and colour every six weeks. NHS dental care and mid-range glasses."}},{"id":7,"name":"Helping Others","minimum":{"value":966,"summary":"£19 for each birthday present.","description":"About £10 each for 12 birthday and 12 Christmas gifts a year."},"moderate":{"value":1842,"summary":"£35 for each birthday present.","description":"About £30 for 12 birthday and 12 Christmas gifts plus £150 a year for helping the family."},"comfortable":{"value":2518,"summary":"£48 for each birthday present.","description":"About £50 each for individual birthday and Christmas gifts, plus £1,000 a year for helping the family."}}]}],"description":"A list of budgets for different demographics and marriage statuses","items":{"$ref":"#/definitions/Budget"}}}},"BudgetPlannerTargetResponse":{"type":"object","properties":{"netTarget":{"type":"number","format":"double","example":36178,"description":"The total, annual net expense that has been entered."},"grossTarget":{"type":"number","format":"double","example":42472.5,"description":"The overall gross target that is required to meet the net target specified in retirement. This figure is gross of income tax."},"netEssentials":{"type":"number","format":"double","example":12913,"description":"The total, annual net expense that has been entered in the 'essentials' category."},"grossEssentials":{"type":"number","format":"double","example":13391.25,"description":"The gross expense for the 'essentials' category. This category will be assumed to be withdrawn first for income tax purposes and will therefore be taxed least."},"netDesirables":{"type":"number","format":"double","example":13363,"description":"The total, annual net expense that has been entered in the 'desirables' category."},"grossDesirables":{"type":"number","format":"double","example":16703.75,"description":"The gross expense for the 'desirables' category. This category will be assumed to be withdrawn second for income tax purposes."},"netLuxuries":{"type":"number","format":"double","example":9902,"description":"The total, annual net expense that has been entered in the 'luxuries' category."},"grossLuxuries":{"type":"number","format":"double","example":12377.5,"description":"The gross expense for the 'luxuries' category. This category will be assumed to be withdrawn third for income tax purposes and will therefore be taxed more than the other two categories."}}},"BudgetPlsaItem":{"type":"object","required":["id","selectedCost"],"properties":{"id":{"type":"integer","format":"int32","description":"The numerical identifier of the expense being entered","minimum":1,"maximum":100},"selectedCost":{"type":"number","format":"double","description":"The annual net expense required","minimum":0,"maximum":10000000}}},"BudgetPlsaTargetParameters":{"type":"object","required":["budgets"],"properties":{"budgets":{"type":"array","example":[{"id":1,"selectedCost":8805},{"id":1,"selectedCost":2664},{"id":1,"selectedCost":3508},{"id":1,"selectedCost":6212},{"id":1,"selectedCost":748},{"id":1,"selectedCost":1842}],"description":"List of all the expenses due in retirement","items":{"$ref":"#/definitions/BudgetPlsaItem"}}}},"BudgetPlsaTargetResponse":{"type":"object","properties":{"netTarget":{"type":"number","format":"double","example":23779,"description":"The total, annual net expense that has been entered."},"grossTarget":{"type":"number","format":"double","example":26973.75,"description":"The overall gross target that is required to meet the net target specified in retirement. This figure is gross of income tax."}}},"SystemError":{"type":"object","properties":{"systemError":{"type":"string","example":"A system error has occurred.","description":"The system error message."}},"description":"A System error message"},"ValidationError":{"type":"object","properties":{"field":{"type":"string","description":"The field that is invalid"},"code":{"type":"string","description":"The type of validation error that has occurred","enum":["REQUIRED","OUT_OF_RANGE","INVALID","INVALID_TOTAL"]},"message":{"type":"string","description":"The validation error message"},"value":{"type":"string","description":"The value that is invalid"}},"description":"Contains details of a error when validating an API input parameter"},"ValidationErrors":{"type":"object","properties":{"errors":{"type":"array","description":"A list of errors from validating the API input parameters","items":{"$ref":"#/definitions/ValidationError"}}},"description":"Contains any errors that have occurred during validation of the API input parameters"}},"securityDefinitions":{"default":{"type":"oauth2","authorizationUrl":"https://api-gateway.prod.powered-by.ev.uk/authorize","flow":"implicit","scopes":{}}},"basePath":"/budgetPlannerRetirement/1.0.0","host":"api-gateway.prod.powered-by.ev.uk"}