Create saving

POST /api/v2/household/{HouseholdGUID}/savings

Bearer auth

This endpoint allows users to create a new saving for a household.

Path parameters

HouseholdGUID string(uuid) Required

The HouseholdGUID of the client.

application/json

Body Required

ClientGUID string(uuid) Required

ClientGUID must be in the household.
SavingsDescription string Required

The following characters are not permitted: \:*"<>|

Maximum length is 100.
SavingsType integer Required

Savings type cannot be changed if saving has a contribution or withdrawal or is the default account.

To retrieve a comprehensive list of acceptable values and their corresponding formatted values, you may make a request to the designated endpoint: /api/v2/household/{HouseholdGUID}/savings/options
Value number(float) Required

Value must not be less than 0 if SavingsType value is not 1.
ValueDate string(date) Required

Date must be before or equal to today.

Dates should be provided in the format "Y-m-d", where "Y" represents the year, "m" represents the month and "d" represents the day. For example, "2023-07-24" represents 24th July, 2023.
JointOwnerClientGUID string(uuid) | null

The following SavingsType can not have a joint owner: 3, 4, 6, 10, 14, 18, 19 and 21. JointOwnerClientGUID must be in the household.
MinimumBalance number(float) | null

Value must not be less than 0.
DependantGUID string(uuid) | null

Must be a dependant of one of the clients within the household.

To retrieve a comprehensive list of acceptable values and their corresponding formatted values, you may make a request to the designated endpoint: /api/v2/household/{HouseholdGUID}/savings/options
ATRGUID string(uuid) | null

To retrieve a comprehensive list of acceptable values and their corresponding formatted values, you may make a request to the designated endpoint: /api/v2/household/{HouseholdGUID}/savings/options
OriginalInvestmentValue number(float) | null
OriginalInvestmentDate string(date) | null

Dates should be provided in the format "Y-m-d", where "Y" represents the year, "m" represents the month and "d" represents the day. For example, "2023-07-24" represents 24th July, 2023.
OriginalInvestmentPercentageWithdrawn number(float) | null
UseAnnualExemptAmount integer
BackOfficeID string | null

Maximum length is 255.
BackOfficeSync integer | null
An integer representing the status of the back office sync:
- 1: Yes
- 2: No
- 3: Only update from back office
PolicyNumber string | null

Maximum length is 50.
ProviderCode string | null

To retrieve a comprehensive list of acceptable values and their corresponding formatted values, you may make a request to the designated endpoint: /api/v2/household/{HouseholdGUID}/savings/options
ISASpecialType integer

Only relevant in the cashflow when the savings type is 3 or 6.
FutureRiskLevelChange integer | null

To retrieve a comprehensive list of acceptable values and their corresponding formatted values, you may make a request to the designated endpoint: /api/v2/household/{HouseholdGUID}/pensions/options
FutureRiskATRGUID string(uuid) | null

This field is required if the value of SavingsType > 5 and FutureRiskLevelChange = 1.

To retrieve a comprehensive list of acceptable values and their corresponding formatted values, you may make a request to the designated endpoint: /api/v2/household/{HouseholdGUID}/savings/options
FutureRiskDateOfChangeBasis integer

This field is required if the value of SavingsType > 5 and FutureRiskLevelChange = 1.

To retrieve a comprehensive list of acceptable values and their corresponding formatted values, you may make a request to the designated endpoint: /api/v2/household/{HouseholdGUID}/pensions/options
FutureRiskDateOfChangeEventGUID string(uuid) | null

This field is required if the value of SavingsType > 5, FutureRiskLevelChange = 1 and FutureRiskDateOfChangeBasis = 4.

To retrieve a comprehensive list of acceptable values and their corresponding formatted values, you may make a request to the designated endpoint: /api/v2/household/{HouseholdGUID}/pensions/options
FutureRiskDateOfChangeAge integer | null

This field is required if the value of SavingsType > 5, FutureRiskLevelChange = 1 and FutureRiskDateOfChangeBasis = 2 or 7. FutureRiskDateOfChangeAge must be in the future

Minimum value is 0, maximum value is 130.
FutureRiskDateOfChangeDate string | null

This field is required if the value of SavingsType > 5, FutureRiskLevelChange = 1 and FutureRiskDateOfChangeBasis = 3. FutureRiskDateOfChangeDate must be in the future

Dates should be provided in the format "Y-m-d", where "Y" represents the year, "m" represents the month and "d" represents the day. For example, "2023-07-24" represents 24th July, 2023.
ExcludeFormattedValues string | null

If set to any value, formatted values will be excluded from the response.
NeverTouch integer | null

NeverTouch cannot be changed if saving is the default account.

To retrieve a comprehensive list of acceptable values and their corresponding formatted values, you may make a request to the designated endpoint: /api/v2/household/{HouseholdGUID}/savings/options

Responses

201 application/json

Success
Hide response attributes Show response attributes object
- success boolean
  
  Default value is true.
- data object
  
  Hide data attributes Show data attributes object
  
  SavingsGUID string(uuid)
  
  ClientGUID string(uuid)
  
  SavingsDescription string
  
  SavingsType integer
  
  Value number(float)
  
  ValueDate string(date)
  
  JointOwnerClientGUID string(uuid)
  
  MinimumBalance number(float)
  
  DependantGUID string(uuid)
  
  ATRGUID string(uuid)
  
  OriginalInvestmentValue number(float)
  
  OriginalInvestmentDate integer(date)
  
  OriginalInvestmentPercentageWithdrawn number(float)
  
  UseAnnualExemptAmount integer
  
  BackOfficeID string
  
  BackOfficeSync integer
  
  PolicyNumber string
  
  ProviderCode string
  
  DefaultAccount integer
  
  ISASpecialType integer
  
  FutureRiskLevelChange integer
  
  FutureRiskATRGUID string(uuid)
  
  FutureRiskDateOfChangeBasis integer
  
  FutureRiskDateOfChangeEventGUID string(uuid)
  
  FutureRiskDateOfChangeAge integer
  
  FutureRiskDateOfChangeDate string
  
  NeverTouch integer
  
  FormattedValues object
403 application/json

Permission error.
Hide response attributes Show response attributes object
- success boolean
  
  Default value is false.
- message string
404 application/json

Household not found
Hide response attributes Show response attributes object
- success boolean
  
  Default value is false.
- message string
422 application/json

Validation error.
Hide response attributes Show response attributes object
- success boolean
  
  Default value is false.
- message string
- data object
  
  Example validation error message.
  
  Hide data attribute Show data attribute object
  
  ClientGUID array[string]
500 application/json

Internal server error.
Hide response attributes Show response attributes object
- success boolean
  
  Default value is false.
- message string

POST /api/v2/household/{HouseholdGUID}/savings

curl \
 --request POST 'https://api.fincalc.co.uk/api/v2/household/{HouseholdGUID}/savings' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --data '{"ClientGUID":"3F0B1C88-6D80-4C17-BB3E-1D68E6D26405","SavingsDescription":"API Test","SavingsType":22,"Value":150000.1,"ValueDate":"2023-04-20","JointOwnerClientGUID":"3F0B1C88-6D80-4C17-BB3E-1D68E6D26405","MinimumBalance":10000.1,"DependantGUID":"4FDA7A23-46AF-45B0-89DB-635544D65147","ATRGUID":"2A30DE74-5AAA-47BE-A419-848A4C40DA42","OriginalInvestmentValue":1500,"OriginalInvestmentDate":"2023-04-20","OriginalInvestmentPercentageWithdrawn":15,"UseAnnualExemptAmount":1,"BackOfficeID":13573,"BackOfficeSync":1,"PolicyNumber":134300454,"ProviderCode":"8379dc94-3bcf-e011-87a9-b8ac6f1693a9","ISASpecialType":1,"FutureRiskLevelChange":1,"FutureRiskATRGUID":"1BE75BD1-917E-4DB1-8059-FA5484147492","FutureRiskDateOfChangeBasis":3,"FutureRiskDateOfChangeEventGUID":"1A58F6C8-90BD-4D2D-9B22-3E1F9C8E15E7","FutureRiskDateOfChangeAge":65,"FutureRiskDateOfChangeDate":"2069-02-01","ExcludeFormattedValues":1,"NeverTouch":2}'

Request examples

{
  "ClientGUID": "3F0B1C88-6D80-4C17-BB3E-1D68E6D26405",
  "SavingsDescription": "API Test",
  "SavingsType": 22,
  "Value": 150000.1,
  "ValueDate": "2023-04-20",
  "JointOwnerClientGUID": "3F0B1C88-6D80-4C17-BB3E-1D68E6D26405",
  "MinimumBalance": 10000.1,
  "DependantGUID": "4FDA7A23-46AF-45B0-89DB-635544D65147",
  "ATRGUID": "2A30DE74-5AAA-47BE-A419-848A4C40DA42",
  "OriginalInvestmentValue": 1500,
  "OriginalInvestmentDate": "2023-04-20",
  "OriginalInvestmentPercentageWithdrawn": 15,
  "UseAnnualExemptAmount": 1,
  "BackOfficeID": 13573,
  "BackOfficeSync": 1,
  "PolicyNumber": 134300454,
  "ProviderCode": "8379dc94-3bcf-e011-87a9-b8ac6f1693a9",
  "ISASpecialType": 1,
  "FutureRiskLevelChange": 1,
  "FutureRiskATRGUID": "1BE75BD1-917E-4DB1-8059-FA5484147492",
  "FutureRiskDateOfChangeBasis": 3,
  "FutureRiskDateOfChangeEventGUID": "1A58F6C8-90BD-4D2D-9B22-3E1F9C8E15E7",
  "FutureRiskDateOfChangeAge": 65,
  "FutureRiskDateOfChangeDate": "2069-02-01",
  "ExcludeFormattedValues": 1,
  "NeverTouch": 2
}

Response examples (201)

{
  "success": true,
  "data": {
    "SavingsGUID": "E4A4A332-C53C-4C33-8D5B-1B846C3D6D6D",
    "ClientGUID": "3F0B1C88-6D80-4C17-BB3E-1D68E6D26405",
    "SavingsDescription": "API Test",
    "SavingsType": 22,
    "Value": 150000.1,
    "ValueDate": "2023-04-20",
    "JointOwnerClientGUID": "3F0B1C88-6D80-4C17-BB3E-1D68E6D26405",
    "MinimumBalance": 10000.1,
    "DependantGUID": "4FDA7A23-46AF-45B0-89DB-635544D65147",
    "ATRGUID": "47017A47-94E5-45BA-BFFB-6C78FB1C31B3",
    "OriginalInvestmentValue": 1500,
    "OriginalInvestmentDate": "2023-04-20",
    "OriginalInvestmentPercentageWithdrawn": 15,
    "UseAnnualExemptAmount": 1,
    "BackOfficeID": "F7FBB6B1-2D90-485C-AE89-9F9FA0426F1E",
    "BackOfficeSync": 1,
    "PolicyNumber": 134300454,
    "ProviderCode": "8379dc94-3bcf-e011-87a9-b8ac6f1693a9",
    "DefaultAccount": 1,
    "ISASpecialType": 1,
    "FutureRiskLevelChange": 1,
    "FutureRiskATRGUID": "D19C98FA-1DB6-4054-8205-C56D56757075",
    "FutureRiskDateOfChangeBasis": 4,
    "FutureRiskDateOfChangeEventGUID": "F3AAED8D-3A5F-44B5-BC6D-9E8C7646C9D7",
    "FutureRiskDateOfChangeAge": 55,
    "FutureRiskDateOfChangeDate": "2069-05-04",
    "NeverTouch": 2,
    "FormattedValues": {
      "Value": "£150,000",
      "ATRGUID": "Medium",
      "ValueDate": "20/04/2023",
      "NeverTouch": "No",
      "SavingsType": "Structured Product",
      "ProviderCode": "1st Source Direct",
      "DependantGUID": "Diane Edwards",
      "DefaultAccount": "No",
      "ISASpecialType": "Junior ISA",
      "MinimumBalance": "£10,000",
      "FutureRiskATRGUID": "Lowest",
      "FutureRiskLevelChange": "Yes",
      "UseAnnualExemptAmount": "Yes",
      "OriginalInvestmentDate": "20/04/2023",
      "OriginalInvestmentValue": "£1,500",
      "FutureRiskDateOfChangeDate": "04/05/2069",
      "FutureRiskDateOfChangeBasis": "Event",
      "FutureRiskDateOfChangeEventGUID": "API's State Pension Age",
      "OriginalInvestmentPercentageWithdrawn": "15%"
    }
  }
}

Response examples (403)

{
  "success": false,
  "message": "You do not have permission to edit the household."
}

Response examples (404)

{
  "success": false,
  "message": "Household not found."
}

Response examples (422)

{
  "success": false,
  "message": "Validation Error.",
  "data": {
    "ClientGUID": [
      "The client guid field is required."
    ]
  }
}

Response examples (500)

{
  "success": false,
  "message": "Failed to create savings in household"
}