Create

POST 
/scenarios/:scenarioId/persons/:personId/goals/relocate

Creates a new Relocate goal in the given scenario identified by {scenarioId} and Person identified by {personId}.

Request

Path Parameters

scenarioId stringrequired

The scenario's id

personId stringrequired

The person's id

application/json

Body

required

currency stringrequired

The currency in which the goal's value is specified. Valid currency code ISO-4217 from the list of supported currencies.

description string

Description of the resource.

desiredAmount number

The desired value of the goal.

enabled boolean

Toggle inclusion of the goal in the simulation.

endDate date-time

End date of the goal. Valid date string in simplified extended ISO-8601 format (YYYY-MM-DDTHH:mm:ss.sssZ). Will be respected only in conjuction with endsOn equals to USER_DEFINED.

endsOn string

Possible values: [USER_DEFINED, ON_RETIREMENT, ON_DEATH]

Can be any of USER_DEFINED, ON_RETIREMENT, ON_DEATH.

expectedAnnualEarnedIncome number

The desired earned income during relocation. This will override the 'percentageOfIncome'.

expectedAnnualLivingExpenses number

The desired spend during relocation. This will override the 'percentageOfExpenditure'.

frequency stringrequired

Possible values: [UNSPECIFIED, ONE_OFF, DAILY, WEEKLY, MONTHLY, QUARTERLY, SEMI_ANNUALLY, ANNUALLY]

The frequency of the goal.

fundingSources object[]
A list of funding sources.
Array [
oneOf
BankOfMumAndDadFundingSource
description string
id string
name string
amount number
currency string
growthRate string
Possible values: [CALCULATED, NONE, CPI, MEDIAN_WAGE_GROWTH, PROPERTY_GROWTH]
maximumAbsoluteSpreadAllowed double
Possible values: <= 1
spreadOverGrowthRate double
Possible values: <= 1
FutureInvestmentPropertyAssetFundingSource
description string
id string
name string
goalId string
The goal id of the Buy to Let goal associated to the property that will be sold in order to fund the goal.
FutureResidentialPropertyAssetFundingSource
description string
id string
name string
goalId string
The goal id of the Buy a House goal associated to the property that will be sold in order to fund the goal.
InvestmentPropertyFundingSource
description string
id string
name string
propertyAssetId string
The id of the investment property that will be sold in order to fund the goal.
LiquidAssetsFundingSource
description string
id string
name string
wrappers string[]
LiquidAssetsNoIncomeFundingSource
description string
id string
name string
wrappers string[]
MortgageFundingSource
description string
id string
name string
amount number
The funding source amount.
annualInterestRate double
Possible values: <= 1
The mortgage annual interest rate.
currency string
The funding source currency. Valid currency code ISO-4217 from the list of supported currencies.
growthRate string
Possible values: [CALCULATED, NONE, CPI, MEDIAN_WAGE_GROWTH, PROPERTY_GROWTH]
maximumAbsoluteSpreadAllowed double
Possible values: <= 1
mortgageType string
Possible values: [FIXED_RATE, ADJUSTABLE_RATE]
The mortgage type. Can be any of (FIXED_RATE, ADJUSTABLE_RATE).
repaymentType string
Possible values: [PRINCIPAL_AMORTIZATION, INTEREST_ONLY_WITH_BALLOON_PAYMENT]
The mortgage repayment type. Can be any of (PRINCIPAL_AMORTIZATION, INTEREST_ONLY_WITH_BALLOON_PAYMENT).
spreadOverGrowthRate double
Possible values: <= 1
termYears int32
The mortgage term years.
OtherLoanFundingSource
description string
id string
name string
amount number
The funding source amount.
annualInterestRate double
Possible values: <= 1
The loan annual interest rate.
currency string
The funding source amount.
growthRate string
Possible values: [CALCULATED, NONE, CPI, MEDIAN_WAGE_GROWTH, PROPERTY_GROWTH]
maximumAbsoluteSpreadAllowed double
Possible values: <= 1
repaymentType string
Possible values: [PRINCIPAL_AMORTIZATION, INTEREST_ONLY_WITH_BALLOON_PAYMENT]
The loan repayment type. Can be any of (PRINCIPAL_AMORTIZATION, INTEREST_ONLY_WITH_BALLOON_PAYMENT).
spreadOverGrowthRate double
Possible values: <= 1
termYears int32
The loan term years.
ResidentialPropertyFundingSource
description string
id string
name string
propertyAssetId string
The id of the residential property that will be sold in order to fund the goal.
SaveFundingSource
description string
id string
name string
saveInYears int32
The number of years for which you would like to save, in order to use the savings to fund the goal.
UKStudentLoanFundingSource
description string
id string
name string
amount number
The funding source amount.
currency string
The funding source amount.
growthRate string
Possible values: [CALCULATED, NONE, CPI, MEDIAN_WAGE_GROWTH, PROPERTY_GROWTH]
maximumAbsoluteSpreadAllowed double
Possible values: <= 1
spreadOverGrowthRate double
Possible values: <= 1
]
growthRate string

Possible values: [CALCULATED, NONE, CPI, MEDIAN_WAGE_GROWTH, PROPERTY_GROWTH]

Can be either of CALCULATED, NONE, CPI, MEDIAN_WAGE_GROWTH, PROPERTY_GROWTH.

id string

The id of the resource.

maximumAbsoluteSpreadAllowed double

Possible values: <= 1

Maximum absolute spread added to growth rate allowed.

minimumAmount numberrequired

The minimum value of the goal.

name string

The name of the resource.

percentageOfExpenditure double

The desired spend during relocation. The expenses will get to previous levels when relocation is over.

percentageOfIncome double

The desired earned income adjustment during relocation. The income will get to previous levels when relocation is over.

priority int32required

The priority of the goal (1 = lowest, 10 = highest).

properties object

Properties of the resource.

property name* object

Properties of the resource.

spreadOverGrowthRate double

Possible values: <= 1

Define the additional spread over the defined growthRate.

startDate date-timerequired

Start date of the goal. Valid date string in simplified extended ISO-8601 format (YYYY-MM-DDTHH:mm:ss.sssZ). Will be respected only in conjuction with startsOn equals to USER_DEFINED.

startsOn string

Possible values: [USER_DEFINED, ON_RETIREMENT, ON_DEATH]

Can be any of USER_DEFINED, ON_RETIREMENT, ON_DEATH.

Responses

201

Created

application/json

Schema

Schema

currency stringrequired

The currency in which the goal's value is specified. Valid currency code ISO-4217 from the list of supported currencies.

description string

Description of the resource.

desiredAmount number

The desired value of the goal.

enabled boolean

Toggle inclusion of the goal in the simulation.

endDate date-time

End date of the goal. Valid date string in simplified extended ISO-8601 format (YYYY-MM-DDTHH:mm:ss.sssZ). Will be respected only in conjuction with endsOn equals to USER_DEFINED.

endsOn string

Possible values: [USER_DEFINED, ON_RETIREMENT, ON_DEATH]

Can be any of USER_DEFINED, ON_RETIREMENT, ON_DEATH.

expectedAnnualEarnedIncome number

The desired earned income during relocation. This will override the 'percentageOfIncome'.

expectedAnnualLivingExpenses number

The desired spend during relocation. This will override the 'percentageOfExpenditure'.

frequency stringrequired

Possible values: [UNSPECIFIED, ONE_OFF, DAILY, WEEKLY, MONTHLY, QUARTERLY, SEMI_ANNUALLY, ANNUALLY]

The frequency of the goal.

fundingSources object[]
A list of funding sources.
Array [
oneOf
BankOfMumAndDadFundingSource
description string
id string
name string
amount number
currency string
growthRate string
Possible values: [CALCULATED, NONE, CPI, MEDIAN_WAGE_GROWTH, PROPERTY_GROWTH]
maximumAbsoluteSpreadAllowed double
Possible values: <= 1
spreadOverGrowthRate double
Possible values: <= 1
FutureInvestmentPropertyAssetFundingSource
description string
id string
name string
goalId string
The goal id of the Buy to Let goal associated to the property that will be sold in order to fund the goal.
FutureResidentialPropertyAssetFundingSource
description string
id string
name string
goalId string
The goal id of the Buy a House goal associated to the property that will be sold in order to fund the goal.
InvestmentPropertyFundingSource
description string
id string
name string
propertyAssetId string
The id of the investment property that will be sold in order to fund the goal.
LiquidAssetsFundingSource
description string
id string
name string
wrappers string[]
LiquidAssetsNoIncomeFundingSource
description string
id string
name string
wrappers string[]
MortgageFundingSource
description string
id string
name string
amount number
The funding source amount.
annualInterestRate double
Possible values: <= 1
The mortgage annual interest rate.
currency string
The funding source currency. Valid currency code ISO-4217 from the list of supported currencies.
growthRate string
Possible values: [CALCULATED, NONE, CPI, MEDIAN_WAGE_GROWTH, PROPERTY_GROWTH]
maximumAbsoluteSpreadAllowed double
Possible values: <= 1
mortgageType string
Possible values: [FIXED_RATE, ADJUSTABLE_RATE]
The mortgage type. Can be any of (FIXED_RATE, ADJUSTABLE_RATE).
repaymentType string
Possible values: [PRINCIPAL_AMORTIZATION, INTEREST_ONLY_WITH_BALLOON_PAYMENT]
The mortgage repayment type. Can be any of (PRINCIPAL_AMORTIZATION, INTEREST_ONLY_WITH_BALLOON_PAYMENT).
spreadOverGrowthRate double
Possible values: <= 1
termYears int32
The mortgage term years.
OtherLoanFundingSource
description string
id string
name string
amount number
The funding source amount.
annualInterestRate double
Possible values: <= 1
The loan annual interest rate.
currency string
The funding source amount.
growthRate string
Possible values: [CALCULATED, NONE, CPI, MEDIAN_WAGE_GROWTH, PROPERTY_GROWTH]
maximumAbsoluteSpreadAllowed double
Possible values: <= 1
repaymentType string
Possible values: [PRINCIPAL_AMORTIZATION, INTEREST_ONLY_WITH_BALLOON_PAYMENT]
The loan repayment type. Can be any of (PRINCIPAL_AMORTIZATION, INTEREST_ONLY_WITH_BALLOON_PAYMENT).
spreadOverGrowthRate double
Possible values: <= 1
termYears int32
The loan term years.
ResidentialPropertyFundingSource
description string
id string
name string
propertyAssetId string
The id of the residential property that will be sold in order to fund the goal.
SaveFundingSource
description string
id string
name string
saveInYears int32
The number of years for which you would like to save, in order to use the savings to fund the goal.
UKStudentLoanFundingSource
description string
id string
name string
amount number
The funding source amount.
currency string
The funding source amount.
growthRate string
Possible values: [CALCULATED, NONE, CPI, MEDIAN_WAGE_GROWTH, PROPERTY_GROWTH]
maximumAbsoluteSpreadAllowed double
Possible values: <= 1
spreadOverGrowthRate double
Possible values: <= 1
]
growthRate string

Possible values: [CALCULATED, NONE, CPI, MEDIAN_WAGE_GROWTH, PROPERTY_GROWTH]

Can be either of CALCULATED, NONE, CPI, MEDIAN_WAGE_GROWTH, PROPERTY_GROWTH.

id string

The id of the resource.

maximumAbsoluteSpreadAllowed double

Possible values: <= 1

Maximum absolute spread added to growth rate allowed.

minimumAmount numberrequired

The minimum value of the goal.

name string

The name of the resource.

percentageOfExpenditure double

The desired spend during relocation. The expenses will get to previous levels when relocation is over.

percentageOfIncome double

The desired earned income adjustment during relocation. The income will get to previous levels when relocation is over.

priority int32required

The priority of the goal (1 = lowest, 10 = highest).

properties object

Properties of the resource.

property name* object

Properties of the resource.

spreadOverGrowthRate double

Possible values: <= 1

Define the additional spread over the defined growthRate.

startDate date-timerequired

Start date of the goal. Valid date string in simplified extended ISO-8601 format (YYYY-MM-DDTHH:mm:ss.sssZ). Will be respected only in conjuction with startsOn equals to USER_DEFINED.

startsOn string

Possible values: [USER_DEFINED, ON_RETIREMENT, ON_DEATH]

Can be any of USER_DEFINED, ON_RETIREMENT, ON_DEATH.

Example (from schema)

{
  "currency": "GBP",
  "description": "My resource's description",
  "desiredAmount": 10000,
  "enabled": true,
  "endDate": "2026-01-01T00:00:00.000Z",
  "endsOn": "USER_DEFINED",
  "expectedAnnualEarnedIncome": 40000,
  "expectedAnnualLivingExpenses": 30000,
  "frequency": "ONE_OFF",
  "fundingSources": [
    {
      "class": "LiquidAssetsFundingSource",
      "description": "Liquid assets funding source",
      "name": "Liquid assets",
      "wrappers": [
        "GENERAL_INVESTMENT_ACCOUNT",
        "TAX_ADVANTAGED",
        "PENSION"
      ]
    }
  ],
  "growthRate": "CALCULATED",
  "id": "1",
  "maximumAbsoluteSpreadAllowed": 0,
  "minimumAmount": 10000,
  "name": "My resource",
  "percentageOfExpenditure": 0.6,
  "percentageOfIncome": 0.8,
  "priority": 1,
  "properties": {
    "property_1": "Value of property 1",
    "property_2": "Value of property 2"
  },
  "spreadOverGrowthRate": 0,
  "startDate": "2025-01-01T00:00:00.000Z",
  "startsOn": "USER_DEFINED"
}

404

Not Found

500

Internal Server Error

Loading...